Webhooks

A QuantaPay envia requisições HTTP POST para a URL de webhook que você configurou quando eventos de pagamento ocorrem. Isso permite que seu servidor reaja aos pagamentos em tempo real.

Configuração

Configure seu webhook emSettings → Payments → Webhook:

• URL do Webhook: Seu endpoint HTTPS (ex:https://yoursite.com/webhook/quantapay)
• Chave Secreta do Webhook: Chave gerada automaticamente para verificação do payload

Payload do Webhook

Quando um pagamento é concluído, a QuantaPay envia uma requisição POST comContent-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 da Transação

Verificação de Assinatura

O campokeyno payload contém suaChave Secreta do Webhook. Se nenhuma Chave Secreta de Webhook estiver configurada, o sistema usará a chave de criptografia da sua conta. Verifique se este valor corresponde ao seu segredo armazenado para confirmar se o webhook é genuíno.

Exemplo em 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';

Exemplo em 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);

Teste 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 Evento

Observação: Webhooks são enviados apenas para transaçõesconcluídas(statusC). Transações expiradas e pendentes não acionam webhooks.

Melhores Práticas

1. Responda Rapidamente

Retorne uma resposta HTTP 200 assim que receber o webhook. Faça o processamento pesado de forma assíncrona.

2. Processamento Idempotente

Seu manipulador de webhook deve ser idempotente — processar o mesmo webhook duas vezes não deve causar cumprimento duplicado. Use oidda transação como uma chave de dedup.

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

3. Verifique a Chave

Sempre verifique se o campokeycorresponde à sua Chave Secreta de Webhook antes de processar.

4. Use HTTPS

Sempre use um endpoint HTTPS para o URL do seu webhook. Endpoints HTTP podem vazar dados confidenciais da transação.

5. Registre Tudo

Registre todos os webhooks recebidos para fins de depuração e auditoria.

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

6. Lide com Falhas com Elegância

Se o seu servidor estiver temporariamente inativo, a entrega do webhook pode ser perdida. Use a APIget-checkout-sessionouget-transactionscomo alternativa para verificar o status do pagamento.