DPT Learn — 收單

USDC 結帳整合

一份務實的工程指南,介紹如何在結帳環節整合 USDC 付款:API 模式、網路選擇、Webhook 冪等性,以及您在正式環境中會遇到的各種故障情形。

要點速覽

USDC 結帳整合遵循一套熟悉的模式:在您的伺服器上建立付款意圖(金額、幣別、網路偏好),從收單機構取得託管結帳頁面 URL 或元件設定,讓買家在自己的錢包中付款,並以冪等方式處理確認 Webhook。最關鍵的工程決策包括:網路選擇(預設使用 Solana 或 Base,費用不到一美分)、Webhook 冪等性(使用訂單 ID + 交易雜湊值)、退款流程(在結帳時收集錢包地址,並提供退款 API),以及錢包簽署環節的流暢體驗(行動裝置透過深層連結喚起錢包,桌面電腦退回使用 QR Code)。實作得當的話,USDC 結帳從頭到尾不到 30 秒即可完成,商家成本視收單機構而定,為 0.3%–1%。

標準 API 形態

USDC 收單 API 大致沿用了 Stripe 推廣開來的付款意圖模式。最基本的介面包括:

  1. 伺服器建立付款意圖

    呼叫 POST /v1/payments,請求本文包含 amount、currency(以法幣報價時為 USD;以穩定幣報價時為 USDC)、settlement_preference(USDC 或法幣)、networks(允許的網路清單)、order_id(您的冪等鍵)、success_url、cancel_url,以及一個供您自行對帳使用的 metadata 資料區塊。

  2. 收單機構回傳結帳頁面 URL 或元件設定

    託管結帳頁面:回傳一個 URL,買家會被重新導向到該位址。嵌入式元件:回傳一份用戶端設定(可公開金鑰、付款意圖 ID),由元件載入。兩種流程都會處理錢包偵測、網路選擇和報價顯示。

  3. 買家在錢包中簽署,鏈上轉帳廣播

    行動裝置:透過深層連結跳轉到 MetaMask、Phantom、Trust 等錢包。桌面電腦:使用 WalletConnect QR Code 或瀏覽器擴充功能彈出視窗。買家核對金額後簽署。

  4. 收單機構等待區塊確認,觸發 Webhook

    收單機構向您發送 POST your_webhook_url 請求,酬載包含 event_type: “payment.succeeded”、order_id、amount、tx_hash、network,以及一個您需要用收單機構的 Webhook 金鑰驗證的簽章。

  5. 伺服器以冪等方式將訂單標記為已付款

    驗證 Webhook 簽章,在資料庫中查詢 (order_id, tx_hash),如尚未標記則標記為已付款,然後啟動履約。

網路選擇

接受哪些網路,是使用者體驗與成本之間的權衡:

  • Solana:網路費用不到一美分,確認時間不到一秒。是小額客單價(AOV)情境的最佳預設選擇。
  • Base:網路費用幾美分,確認需要幾秒。錢包支援廣泛;對加密原生使用者族群來說是不錯的預設選擇。
  • Polygon、Arbitrum:費用和速度與 Base 相近。可以加入,但並非必要。
  • Ethereum 主網:視 Gas 情況,網路費用為 $1–$8+。對小額訂單的買家來說負擔較重。適合高客單價(超過 $500)訂單,或作為備選。
  • Tron:如果您面向亞洲和非洲的 USDT 資金流,值得考慮在 USDC 之外同時支援 TRON 上的 USDT。

Webhook 冪等性

Webhook 會重試,因此您的處理程式必須具備冪等性。標準模式如下:

  1. 使用收單機構的金鑰,透過 HMAC-SHA256 驗證 Webhook 簽章。
  2. 從酬載中擷取 (order_id, tx_hash)。
  3. 在您的 processed_payments 資料表中查詢這一組合。
  4. 如果找到:直接回傳 200 OK,不做任何其他操作。
  5. 如果未找到:插入該列(對這一組合設定 UNIQUE 約束),然後在主訂單資料表中將訂單標記為已付款,再啟動履約。
  6. 將第 5 步包在同一個資料庫交易中,這樣即使流程中途當機,也不會重複履約。

大多數收單 Webhook 都包含一個投遞 ID,請記錄下來以便偵錯,但不要把它當作冪等鍵。網路確認和收單機構的重試可能產生多個重複的 payment.succeeded 事件,它們的投遞 ID 不同,tx_hash 卻相同;去重複必須基於鏈上身分,而不是投遞紀錄。

退款流程

主流的模式有兩種:

  • 原路退款:收單機構將 USDC 退回買家最初付款所用的地址。使用者體驗最簡潔;之所以可行,是因為鏈上付款紀錄中包含來源地址。
  • 退款至指定地址:由買家指定退款目的地(如果買家是從交易所或熱錢包付款,該地址可能與來源地址不同)。大多數收單機構透過帶有 destination_address 的 POST /v1/refunds 支援這一方式。

退款這一環節的網路費用由商家承擔。全額退款和部分退款均受支援。退款本身所需的鏈上確認時間與原始付款相同。

正式環境中的故障情形

  • 買家簽署後放棄。鏈上轉帳已經廣播,但買家在 Webhook 觸發之前關閉了分頁。收單機構仍會透過鏈上監控偵測並確認這筆付款;您的履約流程應由 Webhook 觸發,而不是由頁面重新導向觸發。
  • 買家支付的金額不對。大多數收單機構會在鏈上偵測時拒絕金額不符的付款。部分收單機構允許近似比對(在一定容許誤差範圍內),並在 Webhook 中標明差額。
  • 買家在錯誤的網路上付款。如果買家在 Ethereum 上簽署,而您只接受 Solana,這筆付款將完全不在收單機構的監控範圍內。大多數服務商會透過找回流程退還資金;有些則會導致資金遺失。請在結帳時清楚標明網路選擇。
  • 買家從交易所地址付款。原路退款可能被退回,或進入錯誤的帳戶。對於任何可能產生退款的產品,請在結帳時明確收集退款目的地址。
  • 穩定幣脫鉤。雖然罕見,但確實會發生。如果 USDC 在報價與鏈上結算之間的短暫時間窗內大幅脫鉤,差額將視雙方協議由商家或收單機構承擔。

透過 DPT Acquiring 新增 USDC 結帳

每筆交易 0.3% 起。以 USDC 或法幣當日結算。提供託管結帳頁面 URL 或可嵌入元件。SDK 和 Webhook 文件請前往 merchant.dpt.xyz。

DPT Acquiring · Shopify 與 WooCommerce 整合方式