# Integrate Volet.com non-custodial crypto payments with an AI coding assistant

Use this prompt to integrate Volet.com non-custodial smart contract payments into an existing website or application with an AI coding assistant.

Before starting, provide your AI assistant with:

- Your application's source code.
- The relevant Volet.com EVM or TRON integration guide.
- The Smart contract reference and Payment verification and order tracking guides.
- The corresponding HTML demo, if available.

Copy the following prompt into your AI coding assistant.

---

Integrate Volet.com non-custodial smart contract payments into the existing application using the attached source code and Volet.com documentation.

**Preserve the existing application architecture, frontend, backend, database, authentication, pricing, order management, fulfilment and error-handling conventions.** Do not rebuild unrelated components or introduce unnecessary dependencies.

Read the supplied integration guides and contract reference before making changes. Treat the HTML demos as examples of wallet interaction, not production-ready payment processing implementations.

## Integration requirements

### 1. Create orders on the backend

- Create a unique order before initiating a payment.
- Store the expected blockchain network, asset, payment processor contract, merchant receiving wallet, amount in base units and processing fee settings.
- Obtain all payment configuration values from trusted server-side records.
- Keep the expected payment details immutable after order creation.
- Associate each payment transaction with its corresponding order ID.

The smart contract's `transfer()` function does not accept an `orderId` parameter. Maintain order-to-transaction mapping in the application database.

### 2. Connect customer wallets

For Ethereum and BNB Smart Chain:

- Support MetaMask or another EIP-1193-compatible wallet.
- Support WalletConnect where appropriate, using the application's configured Reown Project ID.
- Validate the connected wallet address and blockchain chain ID.

For TRON:

- Support TronLink.
- Implement mobile wallet connectivity only if compatible with the application's existing architecture.
- Verify that the wallet is connected to TRON Mainnet.

Detect wallet account and network changes before submitting transactions.

Never request or store customer private keys or seed phrases.

### 3. Calculate payment amounts

- Call the processor's `previewPayment(amount, buyerPaysCommission)` function.
- Use the returned `commission` and `totalPay` values rather than calculating processing fees manually.
- Display the order amount, processing fee, total payable amount and a network fee notice.
- Use integer base units for blockchain amounts.
- Apply the correct token decimals for each network, particularly 6 decimals for USDT ERC-20/TRC-20 and 18 decimals for USDT BEP-20.

### 4. Execute payments

For native ETH, BNB and TRX payments:

- Call the appropriate payment processor's `transfer()` function.
- Pass the exact `totalPay` as EVM `value` or TRON `callValue`.
- Ensure the customer has sufficient native assets to cover network fees.

For USDT payments:

- Check the customer's token balance and the processor's allowance.
- Request `approve()` only when the existing allowance is insufficient.
- Handle Ethereum USDT's possible requirement to reset a non-zero allowance to zero before setting a new value.
- Wait for successful approval before submitting the payment transaction.
- Track approval transaction hashes separately from payment transaction hashes.

Never treat a successful token approval as a completed payment.

### 5. Store payment attempts

- Store every payment transaction hash on the backend.
- Associate each payment attempt with its original order.
- Do not overwrite previous pending transactions when customers retry.
- Ensure each transaction is associated with the correct blockchain network and payment processor.
- Persist all transaction and verification records in the database.

Do not rely on browser state or `localStorage` for production payment tracking.

### 6. Implement server-side payment verification

Implement a persistent backend verification worker that continues processing transactions after the customer closes the checkout.

**Never accept a transaction hash, wallet response, browser redirect or client-side payment status as proof of payment.**

For Ethereum and BNB Smart Chain:

1. Retrieve the transaction receipt from a trusted RPC provider.
2. Verify successful execution using `receipt.status === 1`.
3. Wait for the required blockchain finality according to the application's configured risk policy.
4. Find the `PaymentProcessed` event emitted by the approved payment processor contract.
5. Verify that the event's `seller` matches the merchant receiving wallet stored in the order.
6. Verify the buyer address when the order requires a specific payer.
7. Calculate the merchant's received amount using `totalPay - commission` and compare it with the expected amount.
8. For USDT, additionally verify a `Transfer` event emitted by the approved USDT token contract, with `from` equal to the payment processor, `to` equal to the merchant wallet and `value` equal to the expected received amount.

For TRON:

1. Retrieve the solidified transaction receipt using the TRON SolidityNode API.
2. Verify that `receipt.result === 'SUCCESS'`.
3. Decode the `PaymentProcessed` event emitted by the approved TRX or USDT payment processor.
4. Verify the merchant receiving wallet, buyer when applicable and amount received (`totalPay - commission`).
5. For USDT TRC-20, additionally verify the token contract's `Transfer` event from the payment processor to the merchant.
6. Normalise TRON hexadecimal and Base58 addresses before comparing them.

Use the verified `PaymentProcessed` event ABI:

```solidity
event PaymentProcessed(
    address indexed buyer,
    address indexed seller,
    uint256 commission,
    uint256 totalPay
);
```

Use the deployed processor's authenticated event logs and the matching token transfer evidence for payment verification. Do not use calldata alone as proof of payment.

Use the exact processor and token contract addresses approved for the selected network. Never accept arbitrary contract addresses supplied by the frontend.

### 7. Prevent duplicate payments and fulfilment

- Use the transaction hash and event log index to uniquely identify each processed payment event.
- Ensure the same payment event cannot be assigned to multiple orders.
- Maintain a unique order-to-payment association.
- Mark an order as paid only after all verification checks succeed.
- Implement atomic database updates and idempotent fulfilment.
- Ensure repeated verification attempts cannot trigger duplicate deliveries, credits or services.

If multiple events are present in a receipt, inspect all relevant events rather than assuming the first event represents the payment.

### 8. Handle failures and recovery

Implement appropriate handling for:

- Wallet connection rejection.
- Wrong blockchain networks.
- Insufficient token balances or network fees.
- Token approval failures.
- Reverted transactions.
- Unconfirmed or unsolidified payments.
- RPC provider timeouts and rate limits.
- Incorrect merchant wallets, assets or amounts.
- Expired checkouts and late payment confirmations.
- Duplicate transaction submissions.
- Temporary backend outages.

Keep unresolved payments pending or under review when blockchain data is temporarily unavailable. Do not mark them as failed solely because an RPC request times out.

### 9. Add tests

Implement automated unit and integration tests covering:

- Successful native asset and USDT payments.
- Both processing fee settings.
- Correct decoding of `PaymentProcessed` events.
- Correct validation of USDT `Transfer` events.
- Wrong processor or token contract addresses.
- Wrong merchant wallet or payment amount.
- Unsuccessful or unfinalized transactions.
- Missing or incorrect event logs.
- Duplicate transaction hashes and event indexes.
- Repeated verification and duplicate fulfilment.
- Payment retries and late confirmations.
- Blockchain API failures and recovery.

Where available, use the transaction hashes provided in the Volet.com documentation as test fixtures.

### 10. Prepare for production

- Keep the integration behind a feature flag until testing is complete.
- Clearly indicate when a transaction uses mainnet and transfers real funds.
- Use environment-specific configuration for RPC endpoints, WalletConnect Project IDs, processor contracts and merchant wallets.
- Never hard-code private keys, secret API credentials or arbitrary merchant addresses.
- Add structured logging and sufficient transaction information for payment reconciliation.
- Confirm the deployed contract addresses and ABI against the official Volet.com integration configuration.

## Expected deliverables

When the implementation is complete, provide:

1. All modified application files and a summary of the changes.
2. Database migrations and payment record models.
3. Wallet connection and payment transaction handling.
4. Backend payment verification and reconciliation logic.
5. Tests and instructions for running them.
6. Configuration variables and installation commands.
7. Deployment and launch instructions.
8. Any unresolved integration dependencies or assumptions.

**Do not invent contract addresses, ABIs, payment events, merchant wallet details or API credentials.** If required information is missing, identify exactly what the administrator or Volet.com team must provide.

Do not consider the integration production-ready until transaction verification, idempotency and recovery scenarios have been tested successfully.