
How to accept USDT payments on your website with one API call
Accept USDT payments with Suawave: create a deposit address, display the network and QR code, verify callbacks, and update your order after forwarding.
Published , updated
To accept USDT payments with Suawave, create a deposit address with your payout address and an HTTPS callback URL. Show the buyer the address, network and minimum deposit. Verify each callback signature, match the event to your order, and fulfill only after a confirmed callback shows enough USDT was received.
The single API call in the title creates the deposit address. Your website still needs a checkout display and a callback handler. The Suawave quickstart covers that full flow.
1. Choose the network and read the minimum
Use a ticker that identifies both the network and the asset. The examples here use trc20/usdt, which means USDT on TRON. Keep that network visible throughout checkout; showing only “USDT” leaves out information the buyer needs when sending.
Before creating the order, request GET /trc20/usdt/info/:
curl "https://api.suawave.com/trc20/usdt/info/"
Read minimum_transaction_coin from the response. Treat amounts as decimal strings and use exact decimal arithmetic or integer asset units in your application.
Keep minimums and fees tied to their sources:
| Checkout information | Source |
|---|---|
| Minimum deposit for the selected ticker | minimum_transaction_coin from info or create |
| Fee fields for the created address | The create response |
| Amount actually forwarded for a deposit | value_forwarded_coin in its confirmed callback |
The fees and minimums guide explains the deductions. Don’t treat the forwarding-cost estimate endpoint as a quote of the fee deducted from a USDT deposit: it returns a configured ceiling in the network’s native coin.
2. Create the deposit address
Store an order reference and a fresh, unguessable nonce on your server. Put both in your callback URL so the handler can compare them with the stored order later.
Call GET /trc20/usdt/create/ with your payout address and that callback URL. This request follows the quickstart example; replace the illustrative address, order reference and nonce with your own values before using it:
curl -G "https://api.suawave.com/trc20/usdt/create/" \
--data-urlencode "address=TXyzPayoutAddressExample0000000000000" \
--data-urlencode "callback=https://shop.example/hook?order=1001&nonce=7f3a9c" \
--data-urlencode "pending=1"
The short nonce above is a placeholder, not a nonce-generation recipe. Generate yours with your platform’s cryptographic random generator.
Save the returned address_in with the order. This is the buyer’s deposit destination. address_out is your payout destination; mixing them up breaks the checkout flow.
The canonical ticker and callback pair identifies the order. Repeating that pair returns its existing deposit address, and the first call fixes its callback options. A different payout address for the same pair is refused. Use a distinct callback URL for each order you want to track independently.
The API reference describes callback URL canonicalization and the complete create parameters. Use HTTPS for the callback endpoint and URL-encode each query value. Private and loopback callback destinations are refused.
3. Display the deposit address and QR code
Show the buyer the returned deposit address, selected asset and network, order amount and minimum deposit. Keep the amount visible as text even when you show a QR code.
Request GET /trc20/usdt/qrcode/ using the actual address_in from create. This documentation example also uses a placeholder address and an illustrative amount:
curl -G "https://api.suawave.com/trc20/usdt/qrcode/" \
--data-urlencode "address=TDepositAddressExample0000000000" \
--data-urlencode "value=25.5"
The response has qr_code, a PNG data URI for your image source, and payment_uri, the exact text encoded in the QR.
For TRON, the encoded text is only the deposit address. The API validates value but doesn’t include it in the QR payload. The buyer must enter the amount in their wallet. For EVM tokens, a request with value encodes an EIP-681 token transfer request; wallet support varies and the payer may be able to change the amount.
A QR scan doesn’t establish the amount paid. Your callback handler makes that decision from verified payment data.
4. Verify each callback before changing the order
By default, callbacks arrive as GET requests. Setting post=1 at create selects form POST; json=1 selects JSON POST and takes precedence over post=1. Your own callback query parameters remain in the URL.
Read the x-ca-signature header and verify it with the public key from GET /pubkey/. GET verification uses the exact full URL, including its original query order. POST verification uses the raw request body before parsing. Follow the signature verification examples for your language.
After verification, compare the order reference and nonce with your stored values. Check address_in and coin too: for the trc20/usdt ticker, the callback’s coin value is trc20_usdt.
With pending=1, a qualifying deposit can produce these events:
| Callback field | Meaning | Checkout action |
|---|---|---|
pending is "1" |
Deposit detected | Show a waiting state; don’t fulfill |
pending is "0" |
Forwarding transaction confirmed | Evaluate the confirmed amount against the order |
The pending and confirmed events have different UUIDs. Retries of the same event keep the same UUID. Record processed UUIDs durably so a retry can’t trigger fulfillment twice.
5. Record the payment and acknowledge delivery
A confirmed callback includes value_coin, the deposit amount; fee_coin, the amount charged; and value_forwarded_coin, the amount that reached your payout address. Decide which amount your order policy requires and compare it with exact arithmetic.
Persist the event and resulting order change together before acknowledging it. Return HTTP 200 with the plain body *ok* within 30 seconds. For an already processed event, skip the repeated work and return the same acknowledgement.
Callbacks can arrive out of order after retries. A late pending event mustn’t move a confirmed deposit back to waiting. The callback guide describes acknowledgement rules, retries and event order.
If a callback is missing, GET /trc20/usdt/logs/ lets you retrieve forwarding and delivery history using the original callback URL. Use it as a reconciliation fallback. A sent result means forwarding confirmed but the confirmed callback hasn’t been acknowledged, including when retries were exhausted.
What happens with smaller or repeated payments?
What is the minimum USDT deposit?
Read minimum_transaction_coin for your selected ticker instead of copying a fixed amount into checkout. The minimum that applies to a deposit is the one in force when it was first detected.
What if the buyer sends less than the order total?
Distinguish the order total from the ticker minimum. An eligible deposit can still be smaller than your order total. Keep the order unpaid until verified confirmed deposits satisfy your amount policy. Each eligible deposit is forwarded separately and has its own confirmed callback, so deduplicate events before adding amounts.
A deposit below the ticker minimum isn’t forwarded, produces no callback and doesn’t appear in the public logs. Your checkout must make that minimum clear before the buyer sends.
When is a payment confirmed?
For this integration, fulfill on pending equal to "0" after verifying the signature and order details. That event follows confirmation of the forwarding transaction. A detected deposit, a QR scan or an API response from create doesn’t establish that an order has been paid.