Smart contract payments troubleshooting
Use this guide to troubleshoot common issues when accepting non-custodial payments through Volet.com smart contracts on Ethereum, BNB Smart Chain and TRON.
Find the issue below and follow the recommended steps. For contract addresses, parameters and error definitions, see Smart contract reference.
Wallet and network issues
| Issue | Possible cause | How to resolve |
|---|---|---|
| Wallet connection rejected | Customer rejected the request or the wallet is locked | Ask the customer to unlock their wallet and reconnect |
| MetaMask not detected | No compatible browser wallet is installed or available | Install MetaMask or connect using a supported WalletConnect wallet |
| Wrong EVM network | Wallet is connected to a different network than the one selected at checkout | Request a network switch and verify the chain ID |
| WalletConnect connection fails | Invalid Project ID, incorrect configuration or unsupported wallet/network | Check the Reown project configuration and supported networks |
| TronLink not detected | Extension is not installed, enabled or unlocked | Install or unlock TronLink and refresh the page |
| Wrong TRON network | Wallet is connected to a test network or an unexpected network | Switch to TRON Mainnet and verify the active network |
Always verify the wallet address and selected network again before initiating a payment, especially after a wallet connection or network switch.
USDT approval issues
USDT payments may require an approval transaction before the payment processor can transfer tokens.
| Issue | Possible cause | How to resolve |
|---|---|---|
| Approval transaction rejected | Customer rejected the request in their wallet | Allow the customer to retry approval |
| Insufficient allowance | The processor is not authorised to spend the required amount | Check allowance() and request approval for the required amount |
| Ethereum USDT approval fails | Existing non-zero allowance cannot be changed directly to another non-zero amount | Approve 0, wait for confirmation, then approve the required amount |
| Insufficient USDT balance | Customer does not have enough tokens for the total payment | Check balanceOf() against previewPayment().totalPay |
| Approval succeeded but payment is pending | Approval was completed, but the payment transaction has not been submitted or verified | Check the current allowance, then initiate or verify the separate payment transaction |
Important: A successful approve() transaction is not a completed payment. Only the payment processor's transfer() transaction can be used to verify the order payment.
Transaction and contract errors
| Error or issue | Possible cause | How to resolve |
|---|---|---|
InvalidTotalAmountValidation | Native value or callValue does not match the expected payment total | Call previewPayment() again and submit the returned totalPay |
SellerIsBuyer | Buyer and merchant wallet addresses are identical | Check that the merchant receiving wallet differs from the connected buyer wallet |
SellerZeroAddress | Merchant receiving address is the zero address | Configure a valid merchant wallet |
AmountIsZero | Payment amount is zero | Validate the order amount before submitting the transaction |
CommissionExceedsAmount | Processing fee cannot be deducted from the requested amount | Review the order amount and fee setting |
SellerNotWhitelisted | Merchant receiving wallet is not authorised by the processor | Contact Volet.com to check the wallet's authorisation |
EnforcedPause | Payment processing is paused in the contract | Stop submitting payments through the affected processor and contact Volet.com |
| Token transfer fails | Insufficient token balance, allowance or token-specific restrictions | Verify the token contract, balance, allowance and selected network |
| Insufficient gas | Customer does not have enough ETH or BNB for network fees | Ask the customer to maintain sufficient native coin balance |
| Insufficient TRON resources | Customer has insufficient Energy, Bandwidth or available TRX | Review resource requirements and available TRX |
TRON OUT_OF_ENERGY | Contract execution exhausted the available Energy or configured fee limit | Estimate resource consumption and review the transaction's feeLimit |
TronGrid HTTP 429 | API rate limit exceeded | Use a server-side API key and retry requests with backoff |
Contract errors depend on the deployed processor. See Smart contract reference for error definitions.
Payment remains pending
An order may remain pending even after a customer submits a transaction.
| Situation | What to check | Recommended action |
|---|---|---|
| Transaction hash returned, but no receipt | Transaction may not yet be included in a block | Continue checking the same txid |
| Transaction executed but is not finalized | Required network finality has not been reached | Wait for finality before completing the order |
| USDT approval confirmed, but no payment found | Only the approval transaction was submitted | Check whether a separate payment transaction exists |
| Transaction succeeded, but order is still pending | Payment details may not match the order, or backend verification may be incomplete | Compare the processor, asset, recipient, amount and contract call against the order |
| TRON transaction is visible but not solidified | Transaction has not yet appeared in SolidityNode data | Continue checking the solidified transaction receipt |
| RPC request fails or times out | Provider is temporarily unavailable | Retry verification without marking the transaction as failed |
| Customer closed or refreshed the checkout | Browser session ended before payment confirmation | Continue verification through the backend reconciliation worker |
| Checkout expired before payment confirmation | Transaction may confirm after the checkout window closes | Keep tracking submitted payment attempts and reconcile late payments |
Transaction succeeded, but the order is not marked paid
A successful blockchain transaction does not necessarily mean that the correct order was paid.
Your backend must confirm:
- The transaction used the expected payment processor contract.
- The asset and merchant receiving wallet match the order.
- The payment amount and fee settings are correct.
- The merchant received the expected funds.
- The transaction reached the required blockchain finality.
- The transaction hash has not already been used for another order.
If any required detail does not match, do not automatically mark the order as paid. Keep the payment under review for investigation.
For the full verification process, see Payment verification and order tracking.
Contact support
If the issue persists, contact Volet.com and provide:
- Blockchain network and asset.
- Payment transaction hash (
txid), if available. - Approximate date and time of the transaction.
- Merchant order ID.
- Payment processor contract address.
- Error message or description of the issue.
You can contact our team through Volet.com support.
Security: Never share wallet seed phrases, private keys or secret API credentials.
Related
- Smart contract integration — overview of non-custodial payments.
- Ethereum and BNB Smart Chain integration — accept ETH, BNB and USDT.
- TRON integration — accept TRX and USDT TRC-20.
- Smart contract reference — contract addresses, parameters and errors.
- Payment verification and order tracking — verify transactions and reconcile orders.