// documentación

Documentación para desarrolladores

Integra NextCryptoPay en unos minutos. Aquí tienes la forma de una integración típica.

¿Desarrollas con un agente de IA?

Si usas Claude Code, Codex, Cursor o cualquier agente de IA para construir tu proyecto, descarga docs-agent.md y entrégaselo a tu agente: contiene todo lo necesario para integrar NextCryptoPay automáticamente.

Descargar docs-agent.md

1. Crea una clave de API

Genera una clave en Panel → Claves de API. Mantén el secreto en tu servidor, nunca en el navegador.

2. Crea una factura

Envía por POST el monto, la moneda y la cadena al endpoint de facturas, luego redirige al cliente a la URL de checkout devuelta.

3. Recibe webhooks

Enviamos un webhook firmado cuando una factura se paga, está confirmando o expira. Verifica la firma con tu secreto de webhook.

Autenticación

Autentica cada solicitud con tu clave secreta en el encabezado Authorization. Crea claves por tienda en Panel → Claves de API (la clave completa se muestra una sola vez).

Crear una factura

Envía el monto de la orden, la cadena y el activo. Recibes a cambio una payAddress y una checkoutUrl alojada: redirige ahí a tu cliente.

Solicitud

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

Respuesta

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

Seguir el estado del pago

Consulta la factura, o suscríbete a actualizaciones en vivo mediante Server-Sent Events. Estados: PENDING → CONFIRMING → PAID (o 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

Verificar webhooks

En cada cambio de estado enviamos por POST un evento firmado a tu URL de webhook. Verifica el encabezado x-cryptopay-signature (HMAC-SHA256 del cuerpo sin procesar usando el secreto de webhook de tu tienda) antes de confiar en él. Responde 2xx en menos de 5 s: de lo contrario reintentamos con 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)
});

Cadenas soportadas

Tron (USDT/USDC · TRC20), Ethereum (USDT/USDC · ERC20), BSC (USDT · BEP20), Bitcoin (BTC). La comisión es 0.1% por cada pago exitoso, cobrada de tu saldo prepago en USDT (o cubierta por la cuota de tu plan).