Webhooks

QuantaPay envía solicitudes HTTP POST a la URL de webhook que hayas configurado cuando se producen eventos de pago. Esto permite que tu servidor reaccione a los pagos en tiempo real.

Configuración

Configura tu webhook enAjustes → Pagos → Webhook:

• URL del webhook: Tu endpoint HTTPS (p. ej.,https://yoursite.com/webhook/quantapay)
• Clave secreta del webhook: Clave autogenerada para la verificación de la carga útil

Carga útil del webhook

Cuando se completa un pago, QuantaPay envía una solicitud POST conContent-Type: application/json:

{
  "key": "your-webhook-secret-key",
  "transaction": {
    "id": "123",
    "title": "Payment #ORD-12345",
    "description": "",
    "from": "0xCustomerWalletAddress",
    "to": "0xYourWalletAddress",
    "hash": "0xBlockchainTransactionHash",
    "amount": "0.025",
    "amount_fiat": "49.99",
    "cryptocurrency": "eth",
    "currency": "usd",
    "external_reference": "",
    "creation_time": "2026-03-08 10:00:00",
    "status": "C",
    "webhook": "1",
    "vat": "",
    "billing": "",
    "checkout_id": "cs-cs_a1b2c3d4e5f6a1b2c3d4"
  }
}

Campos de transacción

Verificación de la firma

El campokeyen la carga útil contiene suClave secreta del webhook. Si no se ha configurado ninguna clave secreta de webhook, el sistema recurre al uso de la clave de cifrado de su cuenta. Verifique que este valor coincida con su secreto almacenado para confirmar que el webhook es genuino.

Ejemplo de PHP

$payload = json_decode(file_get_contents('php://input'), true);

$webhook_secret = 'your-webhook-secret-key'; // From Settings

if ($payload['key'] !== $webhook_secret) {
    http_response_code(401);
    die('Invalid webhook signature');
}

// Process the payment
$transaction = $payload['transaction'];
$order_id = $transaction['title'];
$amount = $transaction['amount_fiat'];
$status = $transaction['status'];

if ($status === 'C') {
    // Payment completed — fulfill the order
    fulfill_order($order_id, $amount);
}

http_response_code(200);
echo 'OK';

Ejemplo de Node.js

const express = require('express');
const app = express();
app.use(express.json());

const WEBHOOK_SECRET = 'your-webhook-secret-key';

app.post('/webhook/quantapay', (req, res) => {
  const { key, transaction } = req.body;

  // Verify webhook authenticity
  if (key !== WEBHOOK_SECRET) {
    return res.status(401).send('Invalid signature');
  }

  // Process completed payment
  if (transaction.status === 'C') {
    console.log(`Payment received: ${transaction.amount_fiat} ${transaction.currency}`);
    console.log(`Crypto: ${transaction.amount} ${transaction.cryptocurrency}`);
    console.log(`TX Hash: ${transaction.hash}`);

    // Fulfill order logic here
  }

  res.status(200).send('OK');
});

app.listen(3000);

Prueba cURL

# Simulate a webhook (for testing)
curl -X POST https://yoursite.com/webhook/quantapay \
  -H "Content-Type: application/json" \
  -d '{
    "key": "your-webhook-secret-key",
    "transaction": {
      "id": "123",
      "status": "C",
      "amount": "0.025",
      "amount_fiat": "49.99",
      "cryptocurrency": "eth",
      "currency": "usd",
      "hash": "0xabc123..."
    }
  }'

Tipos de eventos

Nota: Los webhooks solo se envían para transaccionescompleted(estadoC). Las transacciones caducadas y pendientes no activan webhooks.

Mejores prácticas

1. Responda rápidamente

Devuelva una respuesta HTTP 200 tan pronto como reciba el webhook. Realice el procesamiento pesado de forma asíncrona.

2. Procesamiento idempotente

Su controlador de webhook debe ser idempotente: procesar el mismo webhook dos veces no debe causar el cumplimiento duplicado. Utilice la transacciónidcomo clave de deduplicación.

// Check if already processed
if (order_already_fulfilled($transaction['id'])) {
    http_response_code(200);
    die('Already processed');
}

3. Verifique la clave

Verifique siempre que el campokeycoincida con su clave secreta de webhook antes de procesar.

4. Use HTTPS

Utilice siempre un punto de conexión HTTPS para la URL de su webhook. Los puntos de conexión HTTP pueden filtrar datos confidenciales de las transacciones.

5. Registrar todo

Registre todos los webhooks entrantes para fines de depuración y auditoría.

error_log('QuantaPay Webhook: ' . json_encode($payload));

6. Manejar los fallos con elegancia

Si su servidor está temporalmente inactivo, es posible que se pierda la entrega del webhook. Utilice laget-checkout-sessiono laget-transactionsAPI como alternativa para verificar el estado del pago.