// dokümantasyon

Geliştirici dokümantasyonu

NextCryptoPay'i birkaç dakikada entegre edin. Tipik bir entegrasyonun ana hatları burada.

Bir yapay zeka ajanıyla mı geliştiriyorsunuz?

Projenizi Claude Code, Codex, Cursor veya herhangi bir yapay zeka ajanıyla geliştiriyorsanız, docs-agent.md dosyasını indirip ajanınıza verin — NextCryptoPay'i otomatik entegre etmek için gereken her şeyi içerir.

docs-agent.md dosyasını indir

1. Bir API anahtarı oluşturun

Panel → API anahtarları bölümünde bir anahtar oluşturun. Sırrı sunucunuzda tutun, asla tarayıcıda değil.

2. Bir fatura oluşturun

Tutarı, para birimini ve zinciri fatura uç noktasına POST edin, ardından müşteriyi dönen ödeme URL'sine yönlendirin.

3. Webhook'ları alın

Bir fatura ödendiğinde, onaylanırken veya süresi dolduğunda imzalı bir webhook göndeririz. İmzayı webhook sırrınızla doğrulayın.

Kimlik doğrulama

Her isteği Authorization başlığındaki gizli anahtarınızla doğrulayın. Panel → API anahtarları bölümünde mağaza başına anahtar oluşturun (tam anahtar bir kez gösterilir).

Bir fatura oluşturun

Sipariş tutarını, zinciri ve varlığı gönderin. Bir payAddress ve barındırılan bir checkoutUrl geri alırsınız — müşterinizi oraya yönlendirin.

İstek

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

Yanıt

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

Ödeme durumunu takip edin

Faturayı yoklayın veya Server-Sent Events aracılığıyla canlı güncellemelere abone olun. Durumlar: PENDING → CONFIRMING → PAID (veya 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'ları doğrulayın

Her durum değişikliğinde webhook URL'nize imzalı bir olay POST ederiz. Güvenmeden önce x-cryptopay-signature başlığını (mağazanızın webhook sırrını kullanarak ham gövdenin HMAC-SHA256'sı) doğrulayın. 5 saniye içinde 2xx döndürün — aksi takdirde geri çekilerek yeniden deneriz.

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

Desteklenen zincirler

Tron (USDT/USDC · TRC20), Ethereum (USDT/USDC · ERC20), BSC (USDT · BEP20), Bitcoin (BTC). Ücret, başarılı ödeme başına %0,1'dir ve ön ödemeli USDT bakiyenizden alınır (veya plan kotanızla karşılanır).