On-chain top-ups

USDT top-up integration: TRC20 and ERC20 collection, on-chain confirmation and balance accounting

A USDT top-up means a user pays the merchant's own blockchain address, after which the merchant system credits the user's internal balance. 稳付pay monitors transactions, verifies confirmation conditions and sends business callbacks. Funds enter the merchant's wallet directly; the platform neither collects nor holds them. Record actual on-chain receipts separately from internal balances, connecting them through reliable order associations and idempotent accounting.

Contents

1. Two networks and merchant-owned wallets

Networks supported by this serviceAsset formConfirm during onboarding
TronUSDT TRC20Tron network, verified USDT contract and merchant receiving address.
EthereumUSDT ERC20Ethereum network, verified USDT contract and merchant receiving address.

Do not rely only on the USDT name or token icon. Tether's official protocol and contract list can help verify the asset on the corresponding network. A token with the same name is not automatically supported USDT. Check the complete address, not just its last few characters.

Customers pay directly into a wallet controlled by the merchant. Activating monitoring requires the specified receiving details, not handing private keys or seed phrases to 稳付pay. An internal USDT balance belongs to the merchant's business ledger; a wallet balance represents on-chain assets. Do not treat them as the same account.

2. Bind the user order before confirming the matching strategy

The merchant first saves the user ID, original top-up order number, selected network, asset, receiving address, payable quantity, expiry time and crediting rules. If the site uses points or another unit of account, also save a snapshot of the conversion, precision and bonus rules for this order; do not change them arbitrarily after payment.

Confirm with the technical team during onboarding how a transfer is matched to its original order. Do not assume the platform allocates a new address for every order, requires a memo or automatically adjusts amounts. When multiple users pay the same amount to one address, the amount and approximate time alone are insufficient. Follow the confirmed matching strategy and refer ambiguous ownership to manual review.

The network, merchant address and payable quantity displayed to users must come from the order saved on the backend. This article uses placeholders such as MERCHANT_WALLET_ADDRESS and ORDER_ID, rather than example addresses to which funds could actually be sent.

Retain address versions and their effective scope when addresses change, and verify old orders against their original configuration. Agree in advance whether split payments are accepted, how they accumulate and how expired orders are handled. Do not automatically combine several equal-value transfers for one user.

3. Six steps from on-chain payment to internal account credit

  1. Create the top-up orderBind the user, network, asset, receiving address and payable quantity.
  2. User checks details and paysSelect the correct network and send USDT to the merchant's own address.
  3. Monitor candidate transactionsIdentify relevant transfer events and retain transaction and event identifiers.
  4. Verify execution and confirmationsCheck the actual receipt and wait for the confirmation conditions configured for the selected network.
  5. Merchant authenticates the callbackVerify the source and content under the separately agreed protocol and match the original order.
  6. Record balances atomicallyPersist event allocation, the top-up ledger entry and the user balance together.
Business callbacks are sent within seconds after configured confirmation conditions are met. This does not mean block confirmations always take only a few seconds.

4. Seeing a transfer does not mean confirmation conditions are met

A wallet showing Sent, a transaction hash, successful broadcast or an observed Transfer event is not sufficient on its own to credit an account. Verify actual execution on the correct network, the verified token contract, actual recipient and USDT quantity, then determine whether confirmation conditions are met. Do not confuse the contract called by the transaction with the recipient named in its event.

TRON's confirmation semantics documentation distinguishes broadcast, execution receipts and solidification. Even on the solidified chain, check whether execution succeeded. Ethereum's finality explanation likewise distinguishes inclusion in a block from reaching finality.

Specific confirmation conditions depend on the network and integration configuration, rather than one fixed number of seconds. Keep the original record and continue verification if node indexing is delayed or a query temporarily fails. Do not infer transfer failure or ask the user to pay again for those reasons.

5. Confirm the USDT callback protocol separately

During onboarding, technical staff specify callback authentication, field definitions, confirmation rules, retries, acknowledgements and active verification methods. The existing Alipay and WeChat collection documentation is not the USDT protocol. Do not reuse its MD5 fields, notification attempt counts, OK acknowledgement or state enumerations without a separate agreement.

After authenticating a notification, the merchant backend checks the original order, network, token contract, receiving address, actual USDT quantity, transaction identifier and confirmations. Determine the user from the saved order, rather than trusting a browser's payment-success claim or an unauthenticated notification. Investigate incomplete information before crediting the balance.

If a notification arrives but the database write fails, handle failure and recovery as agreed. Duplicate notifications and active verification results must enter the same accounting function. Retain authentication and processing records, without placing keys or wallet secrets in public logs.

6. Deduplicate transfer events and update balances atomically

One blockchain transaction may contain multiple transfer events, so deduplicating by transaction hash alone can miss or misattribute receipts. An internal unique event key could combine network + txHash + logIndex or event sequence number. This is a business identifier example, not a published platform field. Use a consistent indexing convention and retain block and event evidence so one receipt event cannot pay multiple orders.

Ethereum's log documentation includes transaction hashes, log indices and a flag for removal due to a reorganization. If confirmations regress or an event changes, stop automatic processing and review the original record instead of treating it as a new transfer and crediting again.

Also lock and check the original order's remaining amount eligible for crediting and its state. Handle duplicate payments, overpayments and split payments under the agreed rules; a new event must not automatically credit the full order amount again.

Authenticate the notification and validate the confirmed receipt event
Begin database transaction
  Lock the original top-up order and user account
  Check the unique event key and its associated order
  If this event has already credited this order: do not credit again
  If another order has already claimed this event: record a conflict; do not apply the same receipt twice
  Otherwise: save the event allocation, unique top-up ledger entry and balance update
Commit transaction
Return the processing result as agreed

Use the verified token contract's decimals to interpret integer smallest-unit amounts, and calculate with fixed-point or exact decimal arithmetic rather than float. Save raw quantities, conversion results and bonus credit separately. Roll back the entire transaction on failure, and use database unique constraints for duplicate or concurrent processing rather than relying only on a check before insertion.

For example, if EVENT_A has already been credited to ORDER_A, return the original processing result when another notification or verification result arrives. If ORDER_B tries to claim EVENT_A, retain the conflict for investigation. Recording other events in the transaction does not mean they all belong to the current top-up order.

7. Handle late payments, amount differences and network fees

SituationHandling principle
Late paymentPreserve the actual receipt, verify the order expiry rules and credit or provide after-sales handling as agreed.
Underpayment or overpaymentRecord the difference between payable and received quantities and verify it as agreed; do not arbitrarily combine it with another order.
Wrong network or tokenStop automatic crediting, verify the asset, address and control over it, then contact technical staff for handling.
Confirmation regression or an unknown resultRetain the event and original order for review, without duplicate credit or an immediate request to transfer again.

Separately confirm the recipient, network, quantity, fees and authorization for a refund; do not assume monitoring automatically refunds payments. Internal reversals need their own ledger entries rather than deleting original records. An on-chain transfer is not automatically undone by changing an internal state.

Sending a TRC20 transaction from a self-controlled wallet involves Tron bandwidth, energy and possible TRX consumption. Ethereum transaction gas fees are paid in ETH. Exchange withdrawals also require checking the exchange's withdrawal fee and actual transfer quantity. Confirm fees for the current network conditions and sending tool instead of applying one fixed rate to every order.

8. Reconcile individual payments and verify the integration

Associate the network, contract, address, transaction event, top-up order, credit ledger entry and user balance. A wallet's total balance can include unrelated receipts and spending, so a balance increase alone does not identify a user's top-up. Also distinguish direct receipt into a merchant-owned wallet from USDT settlement after WeChat or Alipay channel collection; they are different funds processes.

Integration testing should cover at least normal payments, duplicate notifications, concurrent active verification, multiple events in one transaction, equal-amount orders to one address, underpayments, overpayments, late payments, database rollback and confirmation exceptions. Check event allocation and the final balance in every case to ensure nothing is missed or credited twice and the same event is not assigned to two users.

Do funds enter a 稳付pay wallet first?

No. Customers pay directly to the merchant's own address. The platform only provides monitoring and callbacks; it neither collects nor holds funds.

Should balances be credited as soon as a transaction appears on-chain?

First verify execution, the asset, address, quantity and configured confirmation conditions, then let the backend record the credit idempotently.

How do I confirm current support and pricing?

Monitoring and callbacks on Tron and Ethereum are free for small and medium webmasters; enterprise services are charged separately. Contact the technical team to confirm order matching and callback configuration. The standalone payout API is not currently open.

References

The official sources are used to verify assets, on-chain confirmation and network fees. The actual USDT monitoring and callback protocol, confirmation conditions and order-matching rules follow the configuration agreed with the technical team during onboarding.

Confirm integration for your business scenario

Describe your products, order volume, payment methods and settlement needs to confirm the APIs, movement of funds and exception handling item by item.

Contact 稳付pay ↗