Skip to content
Aevum Builder Challenge #1 · $1,500 in USDT prizes · Build Nov 16 – Dec 11Join →

Stablecoin Payments: What Accepting Them Actually Involves

How accepting stablecoin payments works in code: asking for the exact amount, matching transfers to orders, deciding when it's final, refunds and receipts.

Industry Trend
"Stablecoin Payments": glass discs in light, a developer guide to accepting stablecoin payments

A stablecoin payment is a token transfer from the payer's wallet to yours, recorded on a blockchain. You can accept stablecoin payments through a payment provider that handles the chain for you, or directly in your own code. Going direct means your app has to ask for the exact amount, work out which transfer paid which order, decide when a payment counts as final, deal with wrong amounts and refunds, and keep a receipt you can prove.

Each of those jobs comes with the Ethereum standard it rests on and an example in tUSD8, a test stablecoin on QDay's Aevum Testnet that has no real value.

Two Ways to Accept Stablecoin Payments

With a provider, stablecoins are one more option in someone else's checkout. The customer connects a wallet on the provider's page, the provider watches the chain, and your system receives a status update. Some providers can also pay you out in your own currency, so the stablecoin never sits on your balance sheet.

With the direct route, the customer's wallet sends tokens to an address you control, and your code reads the chain to find out what happened. There is no one in between to do the bookkeeping.

JobWith a providerDirect
Ask for the amountProvider's checkoutYour app
Match payment to orderProviderYour code
Decide it's finalProviderYour code
RefundProvider's refund flowA new transfer you send

Pick a provider if you want money in a bank account and card-style operations. Go direct when the payer or the logic already lives on-chain: a contract that settles invoices, a payroll stream, or an AI agent with its own wallet (the case we cover in agent payments). The rest of this guide is about the direct route.

Ask for the Exact Amount, on the Right Network

ERC-20 tokens, tUSD8 among them, keep balances as whole numbers in the token's smallest unit. The token's decimals value tells you where the decimal point goes. The ERC-20 standard gives the example of 8 decimals, which "means to divide the token amount by 100000000 to get its user representation."

tUSD8 uses 6 decimals, so a 25 tUSD8 invoice is 25,000,000 base units. tQDAY, the gas token on Aevum Testnet, uses 18. Mixing the two up asks the customer for a trillion times too much, or credits them with a trillionth of what they paid. Two habits prevent most of these bugs:

  • Keep amounts as integers (bigint in JavaScript) from the moment you price an order to the moment you store the receipt. Convert to a decimal string only for display.
  • Store the decimals next to each token address you accept, in your own config. ERC-20 lists decimals as optional and says other contracts "MUST NOT expect these values to be present," so reading it at runtime from an unknown contract is a weak check.

To hand the request to a wallet, ERC-681 defines a payment-request URL. For an ERC-20 token it names the token contract, the chain, the recipient and the amount in base units. A 25 tUSD8 request on Aevum Testnet looks like this:

ethereum:0x456569838f1d43009A91ebA4263147Afd7233483@44005/transfer?address=0xYourReceivingAddress&uint256=25000000

Keep the @44005 chain ID. Without it, ERC-681 says "the client's current network setting remains effective," which means the customer's wallet sends on whatever network it happens to be on. Put the same URL in a QR code for mobile wallets, and test it with the wallets your customers actually use.

Tell Which Transfer Paid Which Order

None of the top-ranking guides we read explain this step, and getting it wrong means crediting the wrong customer. The ERC-20 Transfer event has three fields:

event Transfer(address indexed _from, address indexed _to, uint256 _value)

There is no memo or reference field. If two customers each send 25 tUSD8 to the same address, the chain shows two transfers that differ only in the sender, and the sender may be a wallet you have never seen. You need a way to attach the order to the payment. Three patterns are common:

PatternHow it identifies the orderWatch out for
Fresh address per orderAny transfer to that address belongs to the orderKey management, and gas to move funds out later
Payment contractThe payer calls pay(orderId), and your contract emits the order IDYou write and test a contract; payers usually approve first
Amount taggingOdd cents (25.000137) identify the orderFees, rounding and collisions break it

A payment contract fits most on-chain apps, because the order ID lands in an event that your indexer, your auditors and the payer can all read. It uses the ERC-20 transferFrom function, which the standard describes as "allowing contracts to transfer tokens on your behalf," so the payer first approves your contract to move the amount. Tokens that implement ERC-2612 let the payer sign that approval instead of sending a separate transaction; check that your token supports it before you rely on it.

Fresh addresses suit payers who send from a plain wallet or an exchange, where calling a contract function is not an option. Amount tagging is fine for a demo and fragile anywhere else.

Per-request protocols such as x402 solve the same matching problem differently: the payment travels inside the HTTP request it pays for. On QDay, the x402 facilitator is live on Aevum Testnet, and mainnet deployment of QDay's payment network is scheduled for Q1 2027.

Watch the Chain Without Trusting the Label

Once a request is out, your code watches for Transfer events. Four rules keep that watcher honest.

Filter by Contract Address

name and symbol are optional strings that any token contract returns about itself, so a token that calls itself tUSD8 proves nothing. Pin the address you accept. On Aevum Testnet, tUSD8 is 0x456569838f1d43009A91ebA4263147Afd7233483.

Skip Zero-Value Transfers

ERC-20 says the Transfer event "MUST trigger when tokens are transferred, including zero value transfers." So your watcher will see events that moved nothing. On Aevum Testnet they are ordinary: across the 300,000 blocks produced between 13 and 17 November 2026, 112 of the 9,710 tUSD8 Transfer events we counted moved zero tokens. All 112 were two contracts sending zero tokens to themselves. Harmless, but a watcher that counted them would mark orders paid for nothing.

Zero-value transfers are also a scam tool. MetaMask's support pages describe address poisoning, where an attacker sends you a transfer from an address made to look like one you use, and note that "usually these are transfers of zero tokens." The hope is that you later copy the lookalike address from your history.

Credit Each Event Once

Use the transaction hash plus the log index as the key, and make crediting idempotent. Watchers restart, RPC calls time out and get retried, and you will rescan ranges you have already seen.

Page Your Queries

The public Aevum Testnet RPC answered our wider queries with "block range too large, max range: 1000," so ask for at most 1,000 blocks at a time. With viem, a watcher for one receiving address looks like this:

import { createPublicClient, http, parseAbiItem } from 'viem'

const client = createPublicClient({ transport: http('https://rpc-test.qday.info') })
const TUSD8 = '0x456569838f1d43009A91ebA4263147Afd7233483'

// start: the next block to scan; receivingAddress: the order's address
const logs = await client.getLogs({
  address: TUSD8,
  event: parseAbiItem('event Transfer(address indexed from, address indexed to, uint256 value)'),
  args: { to: receivingAddress },
  fromBlock: start,
  toBlock: start + 999n, // the public Aevum Testnet RPC allows 1,000 blocks per query
})

for (const log of logs) {
  if (!log.args.value) continue // skips zero-value transfers
  const key = `${log.transactionHash}:${log.logIndex}`
  // credit the order once per key
}

Decide When a Payment Counts as Paid

Ethereum's JSON-RPC API lets you ask a node about several points in the chain, including "latest" (the latest proposed block), "safe" (the latest safe head block) and "finalized" (the latest finalized block). A payment in a block at or below finalized has passed the point the node calls final. A payment that has only reached latest is visible, but it has not got there yet.

Our recommendation is to tie the wait to what you hand over. If you are releasing something cheap that you can still withhold later, such as an API credit or a download, marking the order as paid when the transfer appears in latest is reasonable. If you are shipping goods, releasing a large amount, or doing something you cannot undo, wait until the block containing the payment is at or below finalized. Show the customer two states, "payment seen" and "payment final," so a delay in the second never looks like a failure.

On QDay, finality comes in steps. Transactions are first executed in QDay blocks. Independent validators then check each batch of blocks, and according to the QDay FAQ, "a batch is finalized once an M-of-N threshold of validators agrees." After that, the batch's state root is committed to Abelian. We have not confirmed which of those steps the node's finalized tag reports, but either way it can trail latest by many blocks. Read the tag from the node instead of hard-coding a number of confirmations; viem's getLogs accepts 'finalized' as a block parameter, so you can query up to the final block directly.

Wrong Amounts, Late Payments and Refunds

Decide these rules before launch, because on the direct route every fix is a new transfer that someone has to send.

Late Payments

Give every request an expiry, long enough for a customer to find their wallet and short enough that you can release reserved stock. For a web checkout we would start somewhere between 15 and 30 minutes and adjust from there. Then decide what happens to a payment that arrives after expiry: accept it if the price and stock still hold, or refund it.

Underpayments and Overpayments

For a shortfall, keep the order open and show the remaining amount, accepting a top-up to the same address or order ID. For an excess, either credit the difference to the customer's account or refund it. Whichever you pick, write it down where the customer can see it.

Refunds

On the direct route, a refund is a new transfer you send, and you pay its gas. The tricky part is where to send it. The from address on the original payment may not belong to the customer in any useful sense; it could be an exchange account or a contract wallet, and a transfer back there may never reach them. No standard spells this out; it is our reading of how transfers work, and it is why we suggest asking the customer for a refund address and confirming it. Copy that address from your order record. Transaction history is exactly where address-poisoning transfers land.

Keep a Receipt You Can Prove

Every payment should leave a record that someone else can check against the chain without trusting your database. Store:

  • the order ID and the amount requested, in base units, with the token's decimals
  • the chain ID and the token contract address
  • the transaction hash, log index and block number
  • the payer address and the receiving address
  • when you first saw the payment and when it became final
  • any top-up or refund, with its own transaction hash

With those fields, anyone can open a block explorer and confirm the payment. They also answer two of the judging criteria in the Aevum Builder Challenge #1 starter kit, which asks for code that "handles retries, idempotency, and async failures gracefully" and for "verifiable receipts."

Two things this guide does not settle for you. On the direct route no provider screens payers for you, so checks such as sanctions screening may fall to you, and what is required depends on where your business operates. Get advice before you take real money. And turning stablecoins into money in a bank account is a separate step.

Try It on Aevum Testnet

Aevum Testnet, QDay's live test network, is a place to build all of this without real money. Its chain ID is 44005, and tUSD8, the test version of the USD8 stablecoin, is deployed at 0x456569838f1d43009A91ebA4263147Afd7233483 with 6 decimals. tUSD8 has no real value. Gas on Aevum Testnet is paid in tQDAY, which you can claim from the faucet, and the network uses the same EIP-1559 fee model as Ethereum. QDay's stablecoin paymaster is also live on Aevum Testnet for ERC-4337 smart-contract wallets, so those wallets can pay transaction fees in the stablecoin; regular wallets such as MetaMask still need tQDAY. According to the QDay FAQ, step-by-step documentation, contract addresses and endpoints for it will be published in the docs. The Aevum Testnet getting-started guide walks through adding the network, claiming test tokens and deploying a first contract.

If you want a deadline, the Aevum Builder Challenge #1 runs its build window from 16 November to 11 December 2026, with submissions closing at 08:00 UTC on 11 December. Its tracks include Invoice Payments, Payroll and Vesting, and Confirmation of Payee, which map closely onto matching payments to orders, paying on a schedule, and checking an address before money moves.

Get the next post in your inbox

Testnet releases, developer updates and research from QDay.

EssentialNeeded for the site to work. Always on.
Always on
AnalyticsGoogle Analytics, to understand how the site is used.
AdvertisingGoogle Ads and other ad tags, to measure and personalise our campaigns.