Documentation développeur

Authentification

Authentifiez chaque requête avec votre clé secrète dans l'en-tête Authorization. Créez des clés par boutique dans Tableau de bord → Clés API (la clé complète n'est affichée qu'une fois).

Créer une facture

Envoyez le montant de la commande et l’actif ; la chaîne est facultative. Vous recevez un checkoutUrl hébergé — redirigez-y votre client. Sans chaîne, le client choisit le réseau sur la page de paiement.

Requête

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

Réponse

{
  "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 est l'adresse vers laquelle le client est renvoyé quelques secondes après le paiement. Si vous l'omettez, l'URL de retour de la boutique (Dashboard → Webhooks) est utilisée. Renseignez l'une des deux : sans aucune, le client reste bloqué sur la page de paiement. Ne validez jamais une commande simplement parce que quelqu'un a atteint cette URL : seul un webhook invoice.paid à signature vérifiée prouve le paiement.

Suivre le statut du paiement

Interrogez la facture, ou abonnez-vous aux mises à jour en direct via Server-Sent Events. Statuts : PENDING → CONFIRMING → PAID (ou 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

Vérifier les webhooks

À chaque changement de statut, nous envoyons en POST un événement signé à votre URL de webhook. Vérifiez l'en-tête x-nextcryptopay-signature (HMAC-SHA256 du corps brut à l'aide du secret de webhook de votre boutique) avant de lui faire confiance. Retournez un code 2xx sous 15 s — sinon, nous réessayons avec un délai croissant. Les anciens en-têtes x-cryptopay-* continuent d'être envoyés en parallèle avec des valeurs identiques jusqu'au 31/03/2027 ; dans le code neuf, préférez les noms 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)
});

Chaînes prises en charge

Tron (USDT/USDC · TRC20), Ethereum (USDT/USDC · ERC20), BSC (USDT · BEP20), TON (USDT · jetton), Bitcoin (BTC). Chaque paiement réussi entraîne des frais de plateforme, plafonnés par transaction, prélevés sur votre solde USDT prépayé (ou couverts par le quota de votre forfait). Consultez la page tarifs pour les tarifs en vigueur.