跳至主要內容
Aevum Builder Challenge #1 · 1,500 USDT 獎金 · 11 月 16 日至 12 月 11 日參加 →

穩定幣付款:收款實際要做哪些事

用程式碼接受穩定幣付款如何運作:要求確切金額、把轉帳對應到訂單、決定付款何時最終確定,以及退款和收據。

行業趨勢
「穩定幣付款」:光線中的玻璃圓盤,一份接受穩定幣付款的開發者指南

穩定幣付款是由付款方錢包轉到你錢包的一筆代幣轉帳,記錄在區塊鏈上。你可以透過替你處理區塊鏈事務的支付服務商接受穩定幣付款,也可以直接在自己的程式碼中處理。走直接路線,你的應用程式就要自行要求確切的金額、找出哪筆轉帳支付了哪張訂單、決定付款何時算作最終確定、處理金額錯誤和退款,並保存一份可以證明的收據。

以下每項工作都附上它所依據的以太坊標準,以及一個使用 tUSD8 的例子。tUSD8 是 QDay 的 Aevum 測試網上的一種測試穩定幣,沒有實際價值。

接受穩定幣付款的兩種方式

使用服務商時,穩定幣只是別人結帳流程中多出的一個付款選項。顧客在服務商的頁面上連接錢包,服務商監察區塊鏈,你的系統則收到狀態更新。有些服務商還可以用你自己的貨幣向你付款,讓穩定幣從不出現在你的資產負債表上。

走直接路線時,顧客的錢包把代幣發送到你控制的地址,你的程式碼則讀取區塊鏈,了解發生了甚麼。中間沒有人替你記帳。

工作使用服務商直接處理
要求金額服務商的結帳流程你的應用程式
把付款對應到訂單服務商你的程式碼
決定付款已最終確定服務商你的程式碼
退款服務商的退款流程由你發送一筆新的轉帳

如果你想把錢收進銀行帳戶,並沿用類似銀行卡的營運方式,就選擇服務商。如果付款方或業務邏輯本身已經在鏈上,例如結算發票的合約、串流式發薪,或擁有自己錢包的智能代理(我們在智能代理支付一文中討論的情況),就走直接路線。本指南其餘部分講的都是直接路線。

在正確的網絡上要求確切金額

ERC-20 代幣(包括 tUSD8)以代幣最小單位的整數記錄餘額。代幣的 decimals 值告訴你小數點應該放在哪裡。ERC-20 標準以 8 位小數為例,這「代表要把代幣數量除以 100000000,才得到給用戶看的數值」(means to divide the token amount by 100000000 to get its user representation)。

tUSD8 使用 6 位小數,所以一張 25 tUSD8 的發票是 25,000,000 個基本單位。Aevum 測試網的 gas 代幣 tQDAY 則使用 18 位小數。把兩者搞混,就會向顧客要求高出一萬億倍的金額,或只替他們入帳所付金額的一萬億分之一。兩個習慣可以避免大部分這類錯誤:

  • 從為訂單定價那一刻起,到儲存收據為止,金額都以整數保存(JavaScript 中用 bigint)。只在顯示時才轉換成十進位字串。
  • 在你自己的設定中,把小數位數與你接受的每個代幣地址存放在一起。ERC-20 把 decimals 列為可選,並指出其他合約「不得預期這些值一定存在」(MUST NOT expect these values to be present),所以在執行時從一個不明合約讀取它,是一種靠不住的檢查。

要把付款請求交給錢包,可以用 ERC-681 定義的付款請求 URL。對 ERC-20 代幣而言,它會寫明代幣合約、鏈、收款方,以及以基本單位計的金額。在 Aevum 測試網上,一個 25 tUSD8 的請求是這樣的:

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

請保留 @44005 這個鏈 ID。沒有它,ERC-681 指出「客戶端目前的網絡設定仍然有效」(the client's current network setting remains effective),即顧客的錢包會在它當時剛好所在的網絡上發送。把同一個 URL 放進二維碼供手機錢包使用,並用你的顧客實際使用的錢包來測試。

分辨哪筆轉帳支付了哪張訂單

我們讀過的排名靠前的指南都沒有解釋這一步,而一旦出錯,款項就會記到錯誤的顧客名下。ERC-20 的 Transfer 事件有三個欄位:

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

它沒有備註或參考編號欄位。如果兩位顧客各自向同一個地址發送 25 tUSD8,區塊鏈上會顯示兩筆只有發送方不同的轉帳,而發送方可能是你從未見過的錢包。你需要一種把訂單附加到付款上的方法。常見的模式有三種:

模式如何識別訂單要留意的地方
每張訂單一個新地址轉到該地址的任何轉帳都屬於該訂單密鑰管理,以及日後把資金轉出時要付的 gas
付款合約付款方調用 pay(orderId),你的合約在事件中發出訂單 ID你要編寫並測試一份合約;付款方通常要先授權
金額標記用零碎的尾數(25.000137)識別訂單手續費、四捨五入和金額撞號都會令它失效

付款合約適合大部分鏈上應用,因為訂單 ID 會寫進一個事件,你的索引器、你的審計師和付款方都能讀取。它使用 ERC-20 的 transferFrom 函數,標準形容這個函數「讓合約可以代你轉移代幣」(allowing contracts to transfer tokens on your behalf),所以付款方要先授權你的合約轉移該金額。實現了 ERC-2612 的代幣讓付款方可以簽署這項授權,而不用另外發送一筆交易;依賴這個功能之前,請先確認你的代幣支援它。

每張訂單一個新地址,適合從普通錢包或交易所付款的付款方,因為他們無法調用合約函數。金額標記用於示範沒有問題,用在其他地方就很脆弱。

x402 這類按請求付款的協議,以另一種方式解決同一個對應問題:付款隨它所支付的 HTTP 請求一同傳送。在 QDay 上,x402 結算方已在 Aevum 測試網上線,QDay 支付網絡的主網部署則預定於 2027 年第一季進行。

監察區塊鏈,不輕信代幣的標籤

付款請求發出後,你的程式碼會監察 Transfer 事件。以下四條規則讓監察程式保持可靠。

按合約地址篩選

name 和 symbol 是可選的字串,任何代幣合約都可以自行回傳,所以一個自稱 tUSD8 的代幣甚麼也證明不了。請固定你接受的合約地址。在 Aevum 測試網上,tUSD8 的地址是 0x456569838f1d43009A91ebA4263147Afd7233483。

跳過零值轉帳

ERC-20 規定 Transfer 事件「在轉移代幣時必須觸發,包括零值轉帳」(MUST trigger when tokens are transferred, including zero value transfers.)。因此你的監察程式會看到一些甚麼都沒有轉移的事件。在 Aevum 測試網上,這類事件很平常:在 2026 年 11 月 13 日至 17 日產生的 300,000 個區塊中,我們統計到 9,710 個 tUSD8 Transfer 事件,當中 112 個轉移的代幣數量為零。這 112 個全部是兩份合約向自己發送零個代幣。它們無害,但如果監察程式把它們計算在內,就會把一分錢都沒收到的訂單標記為已付款。

零值轉帳也是一種詐騙工具。MetaMask 的支援頁面描述了地址投毒(address poisoning):攻擊者用一個刻意做得像你常用地址的地址向你發送一筆轉帳,頁面並指出「這些通常是零個代幣的轉帳」(usually these are transfers of zero tokens)。攻擊者希望你日後從交易紀錄中複製這個相似的地址。

每個事件只入帳一次

以交易雜湊值加上日誌索引作為鍵,並讓入帳操作具備冪等性。監察程式會重新啟動,RPC 調用會逾時並被重試,你也會重新掃描已經看過的區塊範圍。

分頁查詢

Aevum 測試網的公共 RPC 對我們範圍較大的查詢回覆「區塊範圍過大,最大範圍:1000」(block range too large, max range: 1000),所以每次最多查詢 1,000 個區塊。使用 viem 時,監察單一收款地址的程式是這樣的:

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
}

決定付款何時算作已付款

以太坊的 JSON-RPC API 讓你向節點查詢鏈上的幾個位置,包括 latest(最新提議的區塊)、safe(最新的安全頭區塊)和 finalized(最新的最終確定區塊)。所在區塊等於或低於 finalized 的付款,已經越過節點所稱的最終確定點。只到達 latest 的付款雖然看得到,但還未到那一步。

我們的建議是按你交付的東西來決定等待多久。如果你交付的是便宜、日後仍可停止提供的東西,例如 API 額度或下載,那麼在轉帳出現在 latest 時就把訂單標記為已付款,是合理的做法。如果你要寄出貨品、發放一大筆金額,或做一件無法撤回的事,就要等到包含該付款的區塊等於或低於 finalized。向顧客顯示兩種狀態:「已偵測到付款」和「付款已最終確定」,這樣第二種狀態出現延誤時,就不會看起來像失敗。

QDay 的最終確定分步完成。交易首先在 QDay 區塊中執行。之後由獨立驗證者檢查每一批區塊,而根據 QDay 常見問題,「一批區塊在達到 M-of-N 門檻的驗證者同意後即告最終確定」(a batch is finalized once an M-of-N threshold of validators agrees)。之後,該批區塊的狀態根會提交到 Abelian。我們尚未確認節點的 finalized 標籤反映的是哪一步,但無論如何,它都可能比 latest 落後許多個區塊。請從節點讀取這個標籤,而不是把確認數寫死;viem 的 getLogs 接受 'finalized' 作為區塊參數,所以你可以直接查詢到最終確定的區塊為止。

金額錯誤、延遲付款和退款

請在上線前定好這些規則,因為在直接路線上,每次修正都是一筆要有人發送的新轉帳。

延遲付款

為每個付款請求設定有效期,要長得足以讓顧客找出錢包,也要短得讓你可以釋放預留的存貨。對網上結帳來說,我們會從 15 至 30 分鐘之間開始,再按情況調整。然後決定有效期過後才到的付款如何處理:如果價格和存貨仍然有效,就接受它,否則就把它退回。

付款不足和付款過多

如果付款不足,保持訂單開啟並顯示尚欠金額,接受顧客向同一地址或同一訂單 ID 補付。如果付款過多,可以把差額記入顧客的帳戶,或把差額退回。無論選擇哪種做法,都要寫在顧客看得到的地方。

退款

在直接路線上,退款是由你發送的一筆新轉帳,gas 由你支付。棘手的是要退到哪裡。原付款的 from 地址未必在任何實際意義上屬於顧客;它可能是交易所帳戶或合約錢包,退回那裡的款項可能永遠到不了顧客手上。沒有任何標準明文說明這一點;這是我們對轉帳運作方式的理解,也是我們建議向顧客索取退款地址並加以確認的原因。請從你的訂單紀錄中複製這個地址。交易紀錄正是地址投毒轉帳出現的地方。

保存一份可以證明的收據

每筆付款都應該留下一份紀錄,讓其他人無需信任你的資料庫,也能對照區塊鏈加以核實。請儲存:

  • 訂單 ID 和要求的金額(以基本單位計),連同代幣的小數位數
  • 鏈 ID 和代幣合約地址
  • 交易雜湊值、日誌索引和區塊編號
  • 付款方地址和收款地址
  • 你首次偵測到付款的時間,以及付款最終確定的時間
  • 任何補付或退款,連同各自的交易雜湊值

有了這些欄位,任何人都可以打開區塊瀏覽器確認付款。它們也回應了 Aevum Builder Challenge #1 入門套件中的兩項評審標準:入門套件要求程式碼「妥善處理重試、冪等性和非同步失敗」(handles retries, idempotency, and async failures gracefully),並要求提供「可驗證的收據」(verifiable receipts)。

有兩件事本指南不會替你決定。在直接路線上,沒有服務商替你篩查付款方,因此制裁篩查這類檢查可能要由你負責,而具體要求取決於你的業務在哪裡營運。收取真實款項之前,請先尋求意見。另外,把穩定幣轉成銀行帳戶裡的錢,是另一個獨立的步驟。

在 Aevum 測試網上試試

Aevum 測試網是 QDay 已上線的測試網絡,你可以在上面把以上這一切做出來,而無需動用真實的錢。它的鏈 ID 是 44005,而 USD8 穩定幣的測試版 tUSD8 部署在 0x456569838f1d43009A91ebA4263147Afd7233483,使用 6 位小數。tUSD8 沒有實際價值。Aevum 測試網上的 gas 以 tQDAY 支付,你可以從水龍頭領取,而網絡採用與以太坊相同的 EIP-1559 手續費模型。QDay 的穩定幣代付手續費服務(paymaster)也已在 Aevum 測試網上線,供 ERC-4337 智能合約錢包使用,讓這些錢包可以用穩定幣支付交易手續費;MetaMask 等一般錢包仍然需要 tQDAY。根據 QDay 常見問題,它的逐步說明文件、合約地址和端點將會在文檔中公布。Aevum 測試網入門指南會帶你完成加入網絡、領取測試代幣和部署第一份合約的步驟。

如果你想給自己定一個期限,Aevum Builder Challenge #1 的開發期由 2026 年 11 月 16 日至 12 月 11 日,作品提交於 12 月 11 日 08:00 UTC 截止。比賽的賽道包括發票付款、薪酬與歸屬,以及收款人確認,分別與把付款對應到訂單、按時間表付款,以及在資金轉出前核對地址緊密對應。

下一篇文章直接送到你的電郵

來自 QDay 的測試網發佈、開發者更新與研究。

必要網站運作所需,一律開啟。
一律開啟
分析Google Analytics,用於了解網站的使用情況。
廣告Google Ads 及其他廣告標籤,用於衡量及個人化我們的推廣活動。