TON Payment tracker

The service provides tools for tracking specific transactions in the blockchain. It supports TON and USDT, allowing users to monitor the status of payments and receive updates about transaction changes through webhooks.

Getting Started

To start using the TON Invoicing Service, follow these steps:

Managing Applications

Once access is granted:

1. An API token will be created automatically.
2. Use the TON Console (opens in a new tab) for UI or API to manage invoices (create, delete, view).
3. Register a webhook on the Overview page (opens in a new tab) to handle invoice status changes.

Payment Creation

curl -X POST https://tonconsole.com/api/v1/services/invoices/invoice \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_API_TOKEN>' \
  -d '{"amount": "1000000", "life_time": 1800, "currency": "USDT", "description": "Example description"}'

{
  "id": "string",
  "status": "pending",
  "amount": "string",
  "description": "string",
  "date_create": 1234567890,
  "date_expire": 1234567890,
  "payment_link": "string",
  "pay_to_address": "0:<hash>"
}

Webhook for Updates

Use a webhook to monitor changes in invoice status. A webhook is a mechanism where Tonconsole sends a POST request to your server whenever an invoice status changes (e.g., from "pending" to "paid").

Here’s how you can handle webhooks on your server:

Example of Webhook Handling (Node.js with Express):

const express = require('express');
const app = express();
 
// Define the webhook endpoint
app.post('/tonconsole-webhooks', (req, res) => {
  try {
    // Parse and log the incoming webhook payload
    const webhookPayload = JSON.parse(req.body);
    console.log('Webhook received:', webhookPayload);
 
    // Respond with a success status to acknowledge the webhook
    res.status(200).send('Webhook received');
  } catch (error) {
    console.error('Error processing webhook:', error);
    res.status(500).send('Internal Server Error');
  }
});
 
// Start the server
app.listen(3000, () => {
  console.log('Webhook server is running on port 3000');
});

Webhook Payload:

Payload type

interface Invoice {
    id: string;
    status: 'pending' | 'paid' | 'cancelled' | 'expired';
    amount: string;
    description?: string;
    date_create: number;
    date_expire: number;
    date_change: number;
    payment_link: string;
    pay_to_address: string;
    paid_by_address?: string;
    overpayment?: string;
}

Payload example

{
  "id": "string",
  "status": "pending | paid | cancelled | expired",
  "amount": "string",
  "description": "string",
  "date_create": 1234567890,
  "date_expire": 1234567890,
  "date_change": 1234567890,
  "payment_link": "string",
  "pay_to_address": "0:<hash>",
  "paid_by_address": "0:<hash>",
  "overpayment": "string"
}

Explanation:

1. /tonconsole-webhooks: Replace this path with your desired endpoint URL.
2. Webhook Payload: This is the structure of the data Tonconsole will send to your endpoint whenever an invoice's status changes.
3. Logging and Acknowledgement: Always log the payload and respond with a 200 status to indicate successful receipt.

Here is an example of how this can be implemented on your side.

Invoice Management

Fetching Invoice by ID

Request:

GET https://tonconsole.com/api/v1/services/invoices/<invoice_id>?api_key=<API_KEY>

Response:

{
  "id": "string",
  "status": "pending | paid | cancelled | expired",
  "amount": "string",
  "description": "string",
  "date_create": 1234567890,
  "date_expire": 1234567890,
  "date_change": 1234567890,
  "payment_link": "string",
  "pay_to_address": "0:<hash>",
  "paid_by_address": "0:<hash>",
  "overpayment": "string"
}

Authentication

Authenticate using either:

• Query parameter: api_key=<API_KEY>.
• Header: Authorization: Bearer <API_KEY>.

Important Details

Invoice Lifetime

• Ensure the invoice life_time is appropriately set.
• Warn users about expiration and block expired payments in your interface.

Overpayment

Overpayment, while uncommon, can occur in specific scenarios. When it happens, Tonconsole will notify you about the overpayment through webhooks or the user interface. The overpayment field in the invoice data reflects the following cases:

• Payments to expired or canceled invoices
  The overpayment field will equal the full amount paid by the user.

• Payments exceeding the required amount
  The overpayment field will represent the difference between the amount paid and the invoice's required amount.

Since Tonconsole focuses solely on tracking transactions and does not process payments directly, handling refunds or adjustments for overpayments will need to be managed on your side. To address such cases, you can use the access credentials to your account holding the funds to implement the necessary refund mechanisms.

This approach ensures you retain full control over your funds while Tonconsole provides reliable real-time monitoring and reporting capabilities.

Tonconsole UI Features

• Manual Invoice Creation (Use the form to create invoices manually)

• Invoice Management (View and manage invoices in the table)

• Statistics (Analyze invoice data using built-in statistics tools)