TON Pay webhooks

TON Pay uses webhooks to notify applications in real-time about transfer events.

How webhooks work

1. A transfer is completed on-chain and indexed by TON Pay.
2. TON Pay generates a webhook payload and signs it using HMAC-SHA256 and the optional API key when it is configured.
3. TON Pay sends a POST request to the webhook URL with the signed payload. The request includes the X-TonPay-Signature header for verification.
4. Verify the signature and process the event payload. Return a 2xx status code to acknowledge receipt.

Configure the webhook URL

Configure the endpoint in TON Pay Merchant Dashboard.

1. Open the TON Pay Merchant Dashboard and sign in to the merchant account.
2. Navigate to the Developer section, then select Webhooks.
3. Enter the webhook URL. In production, the endpoint must use HTTPS. For example, https://thedomain.com/webhooks/tonpay.
4. Save the configuration and use the test feature to verify delivery.

Webhook payload

Event types

import {
  type WebhookPayload,
  type WebhookEventType,
  type TransferCompletedWebhookPayload,
  type TransferRefundedWebhookPayload, // Coming soon
} from "@ton-pay/api";

// Event types
type WebhookEventType =
  | "transfer.completed"
  | "transfer.refunded"; // Coming soon

// Union type for all webhook payloads
type WebhookPayload =
  | TransferCompletedWebhookPayload
  | TransferRefundedWebhookPayload; // Coming soon

transfer.completed

interface TransferCompletedWebhookPayload {
  event: "transfer.completed";
  timestamp: string;
  data: CompletedTonPayTransferInfo; // See API reference
}

Example payloads

Successful transfer:

{
  "event": "transfer.completed",
  "timestamp": "2024-01-15T14:30:00.000Z",
  "data": {
    "amount": "10.5",
    "rawAmount": "10500000000",
    "senderAddr": "<SENDER_ADDR>",
    "recipientAddr": "<RECIPIENT_ADDR>",
    "asset": "TON",
    "assetTicker": "TON",
    "status": "success",
    "reference": "<REFERENCE>",
    "bodyBase64Hash": "<BODY_BASE64_HASH>",
    "txHash": "<TX_HASH>",
    "traceId": "<TRACE_ID>",
    "commentToSender": "Thanks for the purchase",
    "commentToRecipient": "Payment for order #1234",
    "date": "2024-01-15T14:30:00.000Z"
  }
}

Failed transfer:

{
  "event": "transfer.completed",
  "timestamp": "2024-01-15T14:35:00.000Z",
  "data": {
    "amount": "10.5",
    "rawAmount": "10500000000",
    "senderAddr": "<SENDER_ADDR>",
    "recipientAddr": "<RECIPIENT_ADDR>",
    "asset": "TON",
    "assetTicker": "TON",
    "status": "failed",
    "reference": "<REFERENCE>",
    "bodyBase64Hash": "<BODY_BASE64_HASH>",
    "txHash": "<TX_HASH>",
    "traceId": "<TRACE_ID>",
    "commentToSender": "Transaction failed",
    "commentToRecipient": "Payment for order #5678",
    "date": "2024-01-15T14:35:00.000Z",
    "errorCode": 36,
    "errorMessage": "Not enough TON"
  }
}

Placeholders:

• <SENDER_ADDR> - sender wallet address.
• <RECIPIENT_ADDR> - recipient wallet address.
• <REFERENCE> - transfer reference returned by createTonPayTransfer.
• <BODY_BASE64_HASH> - Base64 hash of the transfer body.
• <TX_HASH> - transaction hash.
• <TRACE_ID> - trace identifier.

Payload fields

Verify webhook signatures

Every webhook request includes an X-TonPay-Signature header containing an HMAC-SHA256 signature. Verify this signature to ensure the request comes from TON Pay.

import { verifySignature, type WebhookPayload } from "@ton-pay/api";

app.post("/webhook", (req, res) => {
  const signature = req.headers["x-tonpay-signature"];

  if (!verifySignature(req.body, signature, process.env.TONPAY_API_SECRET)) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  const webhookData: WebhookPayload = req.body;

  // Process the webhook in application-specific logic.
  res.status(200).json({ received: true });
});

Validate webhook requests

Validate fields against the expected transaction data before marking an order as paid.

1. Verify the X-TonPay-Signature header and reject invalid requests.

   if (!verifySignature(payload, signature, apiKey)) { // apiKey is optional and used when configured
     return res.status(401).json({ error: "Invalid signature" });
   }

2. Verify the event type.

   if (webhookData.event !== "transfer.completed") {
     return res.status(400).json({ error: "Unexpected event type" });
   }

3. Check that the reference matches a transaction created earlier.

   const order = await db.getOrderByReference(webhookData.data.reference);
   if (!order) {
     console.error("Order not found:", webhookData.data.reference);
     return res.status(200).json({ received: true }); // Acknowledge to prevent retry
   }

4. Verify the amount matches the expected payment amount.

   if (parseFloat(webhookData.data.amount) !== order.expectedAmount) {
     console.error("Amount mismatch:", {
       expected: order.expectedAmount,
       received: webhookData.data.amount,
     });
     return res.status(200).json({ received: true }); // Acknowledge to prevent retry
   }

5. Verify the payment currency or token.

   if (webhookData.data.asset !== order.expectedAsset) {
     console.error("Asset mismatch:", {
       expected: order.expectedAsset,
       received: webhookData.data.asset,
     });
     return res.status(200).json({ received: true }); // Acknowledge to prevent retry
   }

6. Check status and process only successful transfers.

   if (webhookData.data.status !== "success") {
     await db.markOrderAsFailed(order.id, webhookData.data.txHash);
     return res.status(200).json({ received: true }); // Acknowledge to prevent retry
   }

7. Prevent duplicate processing using the reference.

   if (order.status === "completed") {
     return res.status(200).json({ received: true, duplicate: true });
   }

Complete validation example

import { verifySignature, type WebhookPayload } from "@ton-pay/api";

app.post("/webhooks/tonpay", async (req, res) => {
  try {
    // 1. Verify signature
    const signature = req.headers["x-tonpay-signature"] as string;

    if (!verifySignature(req.body, signature, process.env.TONPAY_API_SECRET!)) {
      console.error("Invalid webhook signature");
      return res.status(401).json({ error: "Invalid signature" });
    }

    const webhookData: WebhookPayload = req.body;

    // 2. Verify event type
    if (webhookData.event !== "transfer.completed") {
      return res.status(400).json({ error: "Unexpected event type" });
    }

    // 3. Find the order
    const order = await db.getOrderByReference(webhookData.data.reference);
    if (!order) {
      console.error("Order not found:", webhookData.data.reference);
      return res.status(200).json({ received: true }); // Acknowledge to prevent retry
    }

    // 4. Check for duplicate processing
    if (order.status === "completed") {
      console.log("Order already processed:", order.id);
      return res.status(200).json({ received: true, duplicate: true });
    }

    // 5. Verify transfer status
    if (webhookData.data.status !== "success") {
      await db.updateOrder(order.id, {
        status: "failed",
        txHash: webhookData.data.txHash,
        failureReason: "Transfer failed on blockchain",
      });
      return res.status(200).json({ received: true });
    }

    // 6. CRITICAL: Verify amount
    const receivedAmount = parseFloat(webhookData.data.amount);
    if (receivedAmount !== order.expectedAmount) {
      console.error("Amount mismatch:", {
        orderId: order.id,
        expected: order.expectedAmount,
        received: receivedAmount,
      });
      return res.status(200).json({ received: true }); // Acknowledge to prevent retry
    }

    // 7. CRITICAL: Verify asset/currency
    const expectedAsset = order.expectedAsset || "TON";
    if (webhookData.data.asset !== expectedAsset) {
      console.error("Asset mismatch:", {
        orderId: order.id,
        expected: expectedAsset,
        received: webhookData.data.asset,
      });
      return res.status(200).json({ received: true }); // Acknowledge to prevent retry
    }

    // All validations passed - acknowledge receipt
    res.status(200).json({ received: true });

    // Process order asynchronously
    await processOrderCompletion(order.id, {
      txHash: webhookData.data.txHash,
      senderAddr: webhookData.data.senderAddr,
      completedAt: webhookData.timestamp,
    });
  } catch (error) {
    console.error("Webhook processing error:", error);
    return res.status(500).json({ error: "Internal server error" });
  }
});

Retry behavior

TON Pay retries failed webhook deliveries.

Delivery outcomes

• Success responses: 2xx. No retry; webhook marked as delivered.
• All other responses: 4xx, 5xx, or network errors. Automatic retry with exponential backoff.

Best practices

• Validate the following fields before marking an order as paid:

  • Signature: authentication;
  • Reference: the transaction exists in the system;
  • Amount: the expected payment is matched;
  • Asset: correct currency or token;
  • Wallet ID: correct receiving wallet;
  • Status: the transaction succeeded.

  // Avoid: trust without verification
  await markOrderAsPaid(webhook.data.reference);
  
  // Prefer: validate and then process
  if (isValidWebhook(webhook, order)) {
    await markOrderAsPaid(order.id);
  }

• Return 2xx only after successful validation, then process the webhook to avoid timeouts.

  app.post("/webhook", async (req, res) => {
    // Validate signature first
    if (!verifyWebhookSignature(...)) {
      return res.status(401).json({ error: "Invalid signature" });
    }
  
    // Quick validations
    if (!isValidWebhook(req.body)) {
      return res.status(400).json({ error: "Invalid webhook data" });
    }
  
    // Acknowledge after validation
    res.status(200).json({ received: true });
  
    // Process in background
    processWebhookAsync(req.body).catch(console.error);
  });

• Implement idempotency. Webhooks may be delivered more than once. Use the reference field to prevent duplicate processing.

  async function processWebhook(payload: WebhookPayload) {
    const order = await db.getOrder(payload.reference);
  
    // Check if already processed
    if (order.status === "completed") {
      console.log("Order already completed:", payload.reference);
      return; // Skip processing
    }
  
    // Process and update status atomically
    await db.transaction(async (tx) => {
      await tx.updateOrder(order.id, { status: "completed" });
      await tx.createPaymentRecord(payload);
    });
  }

• Log all webhook attempts. Log each request for debugging and security auditing.

  await logger.info("Webhook received", {
    timestamp: new Date(),
    signature: req.headers["x-tonpay-signature"],
    reference: payload.data.reference,
    event: payload.event,
    amount: payload.data.amount,
    asset: payload.data.asset,
    status: payload.data.status,
    validationResult: validationResult,
  });

• To receive webhooks in production, ensure corresponding endpoints use HTTPS. Regular HTTP endpoints would be ignored by TON Pay.

• Monitor delivery failures. Set up alerts and review webhook delivery logs in the Merchant Dashboard

• Store transaction hashes. Save txHash to support on-chain verification for disputes.

  await db.updateOrder(order.id, {
    status: "completed",
    txHash: webhookData.data.txHash,
    senderAddr: webhookData.data.senderAddr,
    completedAt: webhookData.timestamp,
  });

Troubleshooting

Next steps