Webhooks

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

Configuração

Configure seu webhook em Configurações → Pagamentos → Webhook:

• Webhook URL: Seu endpoint HTTPS (ex.: https://seusite.com/webhook/quantapay)
• Webhook Secret Key: Chave gerada automaticamente para verificar o payload

Payload do Webhook

Quando um pagamento é concluído, o QuantaPay envia uma requisição POST com Content-Type: application/json:

{
  "key": "your-webhook-secret-key",
  "transaction": {
    "id": "197",
    "biz_id": "QP-20260408-560BF",
    "title": "",
    "description": "",
    "from": "0xCustomerWalletAddress",
    "to": "0xYourWalletAddress",
    "hash": "0xBlockchainTransactionHash",
    "amount": "0.025",
    "amount_fiat": "49.99000000",
    "cryptocurrency": "eth",
    "currency": "usd",
    "external_reference": "your-order-id-123",
    "creation_time": "2026-03-08 10:00:00",
    "status": "C",
    "webhook": "1",
    "vat": "0",
    "billing": "",
    "checkout_id": null,
    "type": "2"
  }
}

Campos da transação

Vinculando pedidos com external_reference

Esta é a forma recomendada de vincular um pagamento QuantaPay ao seu próprio pedido.

Ao criar uma Checkout Session, passe o ID do seu pedido no campo external_reference:

{
  "order_id": "your-order-id-123",
  "external_reference": "your-order-id-123",
  "price": 49.99,
  "currency": "usd"
}

O QuantaPay armazena esse valor e o retorna sem alterações no payload do webhook em transaction.external_reference. Use-o para encontrar e concluir o pedido correto.

Verificação de assinatura

O campo key no payload contém sua Webhook Secret Key. Se não estiver configurada, o sistema usa a chave de criptografia da conta. Configure sempre uma Webhook Secret Key dedicada.

Exemplo PHP

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

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

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

$transaction = $payload['transaction'];

// 2. Check payment is complete
if ($transaction['status'] !== 'C') {
    http_response_code(200);
    die('Not completed');
}

// 3. Match your order using external_reference
$your_order_id = $transaction['external_reference'];
$order = find_order($your_order_id);
if (!$order) {
    http_response_code(200);
    die('Order not found');
}

// 4. Verify amount using float comparison (amount_fiat has 8 decimal places)
$paid_amount = floatval($transaction['amount_fiat']);
$expected_amount = floatval($order->total);
if (abs($paid_amount - $expected_amount) > 0.01 || $transaction['currency'] !== $order->currency) {
    http_response_code(200);
    die('Amount mismatch');
}

// 5. Idempotency check — use biz_id as dedup key
if (order_already_fulfilled($transaction['biz_id'])) {
    http_response_code(200);
    die('Already processed');
}

// 6. Mark order as paid
fulfill_order($your_order_id);

http_response_code(200);
echo 'OK';

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

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

  // 2. Only process completed payments
  if (transaction.status !== 'C') {
    return res.status(200).send('OK');
  }

  // 3. Match your order using external_reference
  const yourOrderId = transaction.external_reference;
  const bizId = transaction.biz_id; // use as dedup key

  console.log(`Payment completed: ${transaction.amount_fiat} ${transaction.currency}`);
  console.log(`Your order: ${yourOrderId}, QuantaPay ref: ${bizId}`);
  console.log(`TX Hash: ${transaction.hash}`);

  // Fulfill order logic here (use biz_id for idempotency)

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

app.listen(3000);

Teste com cURL

curl -X POST https://yoursite.com/webhook/quantapay \
  -H "Content-Type: application/json" \
  -d '{
    "key": "your-webhook-secret-key",
    "transaction": {
      "id": "197",
      "biz_id": "QP-20260408-560BF",
      "status": "C",
      "amount": "0.025",
      "amount_fiat": "49.99000000",
      "cryptocurrency": "eth",
      "currency": "usd",
      "external_reference": "your-order-id-123",
      "hash": "0xabc123..."
    }
  }'

Tipos de eventos

Nota: Webhooks são enviados apenas para transações concluídas (status C). Transações expiradas e pendentes não acionam webhooks.

Boas práticas

1. Responder rapidamente

Retorne HTTP 200 assim que receber o webhook. Processe tarefas pesadas de forma assíncrona.

2. Processamento idempotente

Seu handler deve ser idempotente — processar o mesmo webhook duas vezes não deve causar duplicidade. Use biz_id como chave de deduplicação.

if (order_already_fulfilled($transaction['biz_id'])) {
    http_response_code(200);
    die('Already processed');
}

3. Verificar a chave

Verifique sempre se o campo key corresponde à sua Webhook Secret Key antes de processar.

4. Usar HTTPS

Use sempre um endpoint HTTPS para a URL do webhook.

5. Registrar tudo

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

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

6. Lidar com falhas graciosamente

O QuantaPay não reencaminha automaticamente webhooks com falha. Use a API get-checkout-session ou get-transactions como alternativa para verificar o status do pagamento se o seu servidor ficou temporariamente indisponível.