You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
virt/web/docs/usdt-native-payment.md

3.0 KiB

Native TRC20 USDT payment

The panel creates and settles TRC20 USDT orders without another payment application. The browser still receives an address, an exact six decimal USDT amount, an expiry time, and displays the existing QR dialog.

Database

Import the incremental schema before opening the feature:

mysql -u USER -p DATABASE < sql/usdt_native_payment.sql

Fresh installations already include the same three tables in sql/ss.sql:

  • usdt_wallets: public receiving address pool and scanner state
  • usdt_payment_orders: balance recharge payment orders
  • usdt_chain_transactions: detected transfer evidence and settlement state

The incremental schema permanently removes the retired gateway order tables and configuration entries. It does not remove paylist or user balance data.

Admin configuration

Open /admin/usdt and configure:

  1. One or more public TRON addresses. Never place a private key or seed phrase in the panel.
  2. The CNY value of one USDT. This is a manual settlement rate and should be reviewed regularly.
  3. Order expiry, late-payment grace, and the HTTPS TRON API endpoint.
  4. An optional TronGrid API Key. Without a key, the public endpoint is used and may be subject to stricter rate limits.

When an API Key is saved in the admin page, set USDT_CREDENTIAL_KEY in the PHP-FPM and CLI environments. It must be either 32-byte Base64 or 64 hexadecimal characters. Both environments must use the same value.

The token contract is fixed in code to Tether's TRON USDT contract TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t; it cannot be changed in the admin page.

Cron scanner

Run one scanner every minute from the project directory:

* * * * * cd /YOUR/VIRT-CLOUD/web && /usr/bin/php xcat usdtScanJob >> storage/logs/usdt-scan.log 2>&1

The command has its own non-blocking file lock. It requests only confirmed TRC20 transfers sent to addresses that currently have payable orders, then matches the fixed contract, destination address, exact atomic amount, and order time window. Database transactions and unique event/transaction indexes prevent duplicate balance credit. Paid registration has been removed.

The scanner uses the confirmed-transfer semantics documented by TRON:

Tether's supported-protocol page lists the fixed TRON contract:

Operations

  • Keep the feature in test mode until a small real transfer reaches the correct account and the order changes to paid.
  • Alert on nonzero errors in the cron output and on wallet last_error values shown in /admin/usdt.
  • Transfers with no exact order match are retained as unmatched; they are not automatically credited.
  • The application stores public addresses only. Asset consolidation and wallet signing should run in a separate, more strongly isolated wallet system.