Webhooks

QuantaPay envoie des requêtes HTTP POST à l'URL de webhook que vous avez configurée lorsque des événements de paiement se produisent. Cela permet à votre serveur de réagir aux paiements en temps réel.

Configuration

Configurez votre webhook dansParamètres → Paiements → Webhook:

• URL du webhook: Votre endpoint HTTPS (par exemple,https://yoursite.com/webhook/quantapay)
• Clé secrète du webhook: Clé générée automatiquement pour la vérification de la payload

Payload du webhook

Lorsqu'un paiement est effectué, QuantaPay envoie une requête POST avecContent-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"
  }
}

Champs de transaction

Vérification de la signature

Le champkeydans la charge utile contient votre clé secrète Webhook. Si aucune clé secrète Webhook n'est configurée, le système utilise la clé de chiffrement de votre compte. Vérifiez que cette valeur correspond à votre secret stocké pour confirmer que le webhook est authentique.Clé secrète du webhook. If no Webhook Secret Key is configured, the system falls back to using your account's encryption key instead. Verify this value matches your stored secret to confirm the webhook is genuine.

Exemple 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';

Exemple 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);

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

Types d'événements

Remarque: Les webhooks sont uniquement envoyés pour les transactionscompleted(statutC). Les transactions expirées et en attente ne déclenchent pas de webhooks.

Bonnes pratiques

1. Répondez rapidement

Renvoyez une réponse HTTP 200 dès que vous recevez le webhook. Effectuez le traitement lourd de manière asynchrone.

2. Traitement idempotent

Votre gestionnaire de webhook doit être idempotent : le traitement du même webhook deux fois ne doit pas entraîner une exécution en double. Utilisez le champidcomme clé de déduplication.

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

3. Vérifiez la clé

Vérifiez toujours que le champkeycorrespond à votre clé secrète Webhook avant de traiter.

4. Utilisez HTTPS

Utilisez toujours un point de terminaison HTTPS pour l'URL de votre webhook. Les points de terminaison HTTP peuvent divulguer des données de transaction sensibles.

5. Tout enregistrer

Enregistrez tous les webhooks entrants à des fins de débogage et d'audit.

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

6. Gérer les échecs avec élégance

Si votre serveur est temporairement hors service, la livraison du webhook risque d'être manquée. Utilisez l'get-checkout-sessionou l'get-transactionsAPI comme solution de repli pour vérifier l'état du paiement.