Skip to Content
API 參考總覽
View as Markdown

API 參考

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

本頁列出供商家整合使用的 endpoint。若某個 endpoint 沒有獨立頁面， 會在相關的概念頁面中說明。

/b2b/v1/* 下的 endpoint 以你的 secret key(sk_…)做 HMAC 簽章。這是你的後端呼叫的介面。商家儀表板與託管結帳使用各自的 endpoint，不屬於整合 API。

結帳

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,而你想在儀表板顯示之前的嘗試時很有用。

訂單

訂單是永久的計費實體。同一個訂單可以對應多個結帳 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。 你可以從後端(見下方)或商家儀表板鑄造 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)。

退款生命週期(建立後)

兩種流程皆適用。下方 endpoint 操作的是退款本身(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 Pay 能結算的所有鏈(主網 + 測試網，依環境過濾)。
GET/v1/supported/tokens上述鏈上的所有穩定幣。
GET/v1/supported/currenciesorder.currency 接受的幣別。

健康狀態

MethodPath驗證用途
GET/health無(公開)Liveness 檢查。回傳 {"status":"ok"}。請把你的線上監控指向這裡。

Cursor 分頁

每個列表 endpoint 接受相同 query 參數、回傳相同信封。Cursor 為不透明字串，用來取代 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 視為不透明字串。

本頁未涵蓋的部分

本頁涵蓋供商家整合使用的 endpoint。若你需要未列出的 endpoint 或 OpenAPI spec，請聯絡 support。

JavaScript / 瀏覽器身分驗證