Skip to Content
API 參考總覽

API 參考

以下所有 endpoint 都使用 JSON,寄存於 https://api.infraio.xyz (prod)或 https://api-dev.infraio.xyz(test),並以 HMAC-SHA256 驗證 — 請見身分驗證了解簽章 流程，以及錯誤了解錯誤信封結構。

本頁是索引。每一列會連結到目前最深入的說明;如果某一列只列出路徑， 代表該 endpoint 今天就存在，但是在相關概念頁面內聯說明，而非有獨立的 參考頁面。

Gateway 路徑前綴與其驗證模型:

  • /b2b/v1/* — 以你的 secret key(sk_…)做 HMAC 簽章。 商家後端介面。
  • /payment/v1/* — Bearer JWT(儀表板 session)。供商家儀表板 前端使用;非給第三方整合者。
  • /pub/v1/* — Bearer-of-truth 在路徑中(退款申請的 rfqt_… token)。無憑證。可在瀏覽器中安全呼叫。
  • /checkout/:key/* — 託管結帳流程的公開前綴。key 是建立時 回傳的 cst_… session key;呼叫者只有買家的瀏覽器。無憑證。

結帳

MethodPath用途備註
POST/b2b/v1/checkout-sessions/quick一次呼叫建立 session — 訂單 + 結帳 session 一起鑄造。請求 body 與範例見快速入門。
POST/b2b/v1/checkout-sessions對既有訂單建立 session。當你的平台已經有自己的訂單模型，且每次嘗試想要一個 session 時使用。兩步驟流程。
GET/b2b/v1/checkout-sessions/by-order/{order_id}列出對某訂單曾鑄造過的所有 session。當買家放棄一個 session,而你想在儀表板顯示之前的嘗試時很有用。
GET/checkout/{session_key}公開 — 託管結帳頁面用這個取得資料。僅含買家面向的欄位(無內部參考)。無需簽章;以 session_key 作為 bearer-of-truth。
POST/checkout/{session_key}/intent公開 — 在託管頁面上選擇付款方式。發出帶有存款位址的 PaymentIntent。由 checkout-web 在使用者選擇方式時呼叫。
POST/checkout/{session_key}/verify公開 — 讓買家貼上 tx hash 以略過確認等待。若 hash 錯誤，會 fall through 到 chain watcher。

訂單

訂單是永久的計費實體。同一個訂單可以對應多個結帳 session(例如買家 放棄、重試)。

MethodPath用途備註
POST/b2b/v1/orders不建立 session 直接建立訂單。當你想晚一點寄付款連結給買家、而非立即重導時使用。
GET/b2b/v1/orders/{id}讀取單一訂單，含 line items + 狀態。狀態:PENDING → PAID | PARTIAL_PAID | CANCELED。退款後:PARTIALLY_REFUNDED | REFUNDED。
GET/b2b/v1/orders/by-merchant/{merchant_id}以 cursor 分頁列出你的訂單。Cursor 協定詳見Cursor 分頁。
PATCH/b2b/v1/orders/{id}/cancel將未付款訂單標記為取消。發出 order.canceled。訂單已付款時會失敗。
PATCH/b2b/v1/orders/{id}/reopen反轉自動取消(canceled_reason=payment_timeout)。當買家在 TTL 過期後回來時很有用。

退款

Saga 流程與 token 生命週期請見退款概念頁。

商家發起

MethodPath用途備註
POST/b2b/v1/merchants/{merchant_id}/refunds商家發起的退款。自動核准(跳過 PENDING)。立即發出 payment.refund.approved。

客戶發起 — 退款申請 token

買家在我們的託管頁面填寫退款表單;你只需要鑄造 token 並交付 URL。 有兩個鑄造路徑(後端用 HMAC、儀表板用 JWT)、三個公開 token 路徑 (讀取情境、提交、申請續期),以及兩個儀表板專用的續期處理路徑。

MethodPath驗證用途
POST/b2b/v1/merchants/{merchant_id}/refund-requestsHMAC(sk_…)從你的後端鑄造 token。Body:{ref_type, ref_value, amount, ttl_seconds?, metadata?, hide_summary?, hide_header?}。ref_type 為 order_id / order_number / session_id / session_key 之一;ref_value 是對應的識別碼。amount 是必填,鎖定買家可以提交的上限。預設 TTL 30 分鐘。發出 refund_request.created(source: b2b)。
POST/payment/v1/merchants/{merchant_id}/refund-requestsJWT(儀表板)從商家儀表板的 Issue Refund modal 鑄造 token。Body 結構與 B2B 變體相同。預設 TTL 24 小時。發出 refund_request.created(source: dashboard)。
GET/pub/v1/refund-requests/{token}路徑中的 token公開 — checkout-web 讀取表單情境(訂單摘要、鎖定金額、當前有效狀態)。
POST/pub/v1/refund-requests/{token}/submit路徑中的 token公開 — 買家提交表單。Body:{reason, refund_to_address, amount?, metadata?}。amount 為選填 — 省略時使用商家鎖定的連結金額;有值時伺服器強制 amount ≤ locked amount。建立 Refund 列，發出 payment.refund.requested,回傳 {link_token, refund_id} 用於收據頁。
POST/pub/v1/refund-requests/{token}/request-renewal路徑中的 token公開 — 買家在過期後申請新的連結。Body:{customer_note?}。發出 refund_request.renewal_requested。
GET/payment/v1/merchants/{merchant_id}/refund-requests/renewalsJWT(儀表板)為商家的續期 widget 列出待處理的 RENEWAL_REQUESTED token。Cursor 分頁。
POST/payment/v1/merchants/{merchant_id}/refund-requests/renewals/{token}/issue-newJWT(儀表板)核准續期 — 鑄造新的 ACTIVE token,並讓舊 token 失效。發出 refund_request.renewed + refund_request.created(source: renewal)。
GET/payment/v1/merchants/{merchant_id}/refund-requests/by-order/{order_id}JWT(儀表板)列出對某訂單曾鑄造過的所有 refund-request token,含有效狀態。最新優先。
POST/payment/v1/merchants/{merchant_id}/refund-requests/{token}/send-emailJWT(儀表板)將退款申請連結以 email 寄送給客戶。Body:{to}。發出 refund_request.email_send_requested。
POST/payment/v1/merchants/{merchant_id}/refund-requests/{token}/cancelJWT(儀表板)商家 kill-switch — 將 ACTIVE 或 RENEWAL_REQUESTED 翻為 CANCELED。Body:{reason?}。冪等:狀態已轉換後再次呼叫會回傳成功且不重複發送事件。第一次轉換時發出 refund_request.canceled。

退款生命週期(建立後)

兩種流程皆適用。下方 endpoint 操作的是 Refund 列(id 開頭 rfn_…), 而非 request token。

MethodPath用途備註
GET/b2b/v1/refunds/{id}讀取單筆退款。狀態:PENDING → APPROVED → EXECUTED | REJECTED。
GET/b2b/v1/refunds/by-merchant/{merchant_id}以 cursor 分頁列出你的退款。—
POST/b2b/v1/refunds/{id}/approve核准 PENDING 的退款(僅客戶發起 — 商家發起一開始就是 APPROVED)。加密貨幣:狀態為 APPROVED,接著呼叫 /submit-tx。
POST/b2b/v1/refunds/{id}/reject駁回 PENDING 退款。發出 payment.refund.rejected。
POST/b2b/v1/refunds/{id}/submit-tx僅加密貨幣 — 蓋上你已廣播的鏈上 tx hash。Body:{tx_hash, network, token_address} — 三個都必填。

Catalog(唯讀)

MethodPath用途
GET/v1/supported/networksInfraIO 能結算的所有鏈(主網 + 測試網，依環境過濾)。
GET/v1/supported/tokens上述鏈上的所有穩定幣。
GET/v1/supported/currenciesorder.currency 接受的法幣。
GET/v1/merchants/payment-methods此商家已啟用的方式 — 平台 catalog 與每商家開關的交集。供 checkout-web 使用。
GET/v1/public/merchants/{merchant_id}/branding公開 — 結帳頁面用來套用品牌外觀。

健康狀態

MethodPath驗證用途
GET/health無(公開)單純的 liveness 探測 — 回傳 {"status":"ok"}。這個(沒有 /v1 前綴)是唯一無需驗證的健康端點 — 把你的 k8s / 線上監控指向這裡。
GET/payment/v1/merchants/{merchant_id}/health儀表板 JWT每商家健康視圖 — 近期 intent 結算率、sweep backlog。適合你自己的 status page。需要儀表板 session token,不是 B2B API key。僅能在 /payment/ gateway 前綴下存取 — 沒有前綴的 /v1/... 路徑並未公開路由。
GET/payment/v1/stats/health儀表板 JWT跨商家工作區樹的彙總健康。不是公開的 liveness 探測 — 它位於 /payment/ gateway 前綴下與其餘部分相同的 JWT 驗證之後。

Cursor 分頁

每個列表 endpoint 接受相同 query 參數、回傳相同信封。我們使用不透明的 cursor(base64url 編碼的 (created_at, id)),而非 offset, 因此在一列於滾動中加入時，頁面不會錯位。

Query param型別預設備註
cursorstring—不透明 — 請逐字複製前次回應的 next_cursor。
limitint201..100。
sort_dir'asc' | 'desc'desc依 (created_at, id) 排序。
from / toRFC3339—選填的時間視窗過濾。
searchstring—支援的地方做自由文字過濾。

回應信封:

{
  "orders": [ /* page rows */ ],
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNS0...",
  "has_next": true
}

has_next 永遠存在。next_cursor 在 has_next 為 false 時省略。 不要嘗試解析 cursor — 它的結構是內部的，且會變動。

本頁未涵蓋的部分

本索引涵蓋商家面向的介面 — /admin/*(儀表板工具、KYB 審查、網路 管理)以及內部 gRPC 路由刻意未列出。由 swag 產生的 OpenAPI spec 涵蓋完整介面;若你需要，請聯絡 support,我們會分享當前的快照。

JavaScript / 瀏覽器身分驗證