Documentación para desarrolladores

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 importe del pedido y el activo; la cadena es opcional. Recibirás un checkoutUrl alojado: redirige allí a tu cliente. Sin cadena, el cliente elige la red en la página de pago.

Solicitud

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

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

redirectUrl es adonde se envía al cliente unos segundos después de pagar. Si lo omites, se usa la URL de retorno de la tienda (Dashboard → Webhooks). Configura una de las dos: sin ninguna, el cliente se queda en la página de pago sin forma de volver a tu tienda. Nunca entregues un pedido solo porque alguien llegó a esa URL: solo un webhook invoice.paid con firma verificada demuestra el pago.

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-nextcryptopay-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 15 s: de lo contrario reintentamos con backoff. Las cabeceras antiguas x-cryptopay-* se siguen enviando en paralelo con valores idénticos hasta el 31/03/2027; en código nuevo usa los nombres 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)
});

Cadenas soportadas

Tron (USDT/USDC · TRC20), Ethereum (USDT/USDC · ERC20), BSC (USDT · BEP20), TON (USDT · jetton), Bitcoin (BTC). Cada pago correcto conlleva una comisión de plataforma con un tope por transacción, que se cobra de su saldo prepago en USDT (o se cubre con el cupo de su plan). Consulte la página de precios para las tarifas vigentes.