<!-- Source: https://docs.infraio.xyz/zh-TW/api-reference -->
<!-- Last updated: 2026-10-04 -->

# API 參考

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

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

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

## 結帳

| Method | Path | 用途 | 備註 |
| --- | --- | --- | --- |
| `POST` | `/b2b/v1/checkout-sessions/quick` | 一次呼叫建立 session — 訂單 + 結帳 session 一起鑄造。 | 請求 body 與範例見[快速入門](https://docs.infraio.xyz/zh-TW/get-started/quickstart#2-create-a-checkout-session-server)。 |
| `POST` | `/b2b/v1/checkout-sessions` | 對*既有*訂單建立 session。當你的平台已經有自己的訂單模型，且每次嘗試想要一個 session 時使用。 | 兩步驟流程。 |
| `GET` | `/b2b/v1/checkout-sessions/by-order/{order_id}` | 列出對某訂單曾鑄造過的所有 session。 | 當買家放棄一個 session,而你想在儀表板顯示之前的嘗試時很有用。 |

## 訂單

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

| Method | Path | 用途 | 備註 |
| --- | --- | --- | --- |
| `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 分頁](#cursor-分頁)。 |
| `PATCH` | `/b2b/v1/orders/{id}/cancel` | 將未付款訂單標記為取消。發出 `order.canceled`。 | 訂單已付款時會失敗。 |
| `PATCH` | `/b2b/v1/orders/{id}/reopen` | 反轉自動取消(`canceled_reason=payment_timeout`)。 | 當買家在 TTL 過期後回來時很有用。 |

## 退款

Saga 流程與 token 生命週期請見[退款概念頁](https://docs.infraio.xyz/zh-TW/concepts/refunds)。

### 商家發起

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

### 客戶發起 — 退款申請 token

買家在我們的託管頁面填寫退款表單;你只需要鑄造 token 並交付 URL。
你可以從後端(見下方)或商家儀表板鑄造 token。續期與取消在儀表板中處理。

| Method | Path | 驗證 | 用途 |
| --- | --- | --- | --- |
| `POST` | `/b2b/v1/merchants/{merchant_id}/refund-requests` | HMAC(`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。

| Method | Path | 用途 | 備註 |
| --- | --- | --- | --- |
| `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(唯讀)

| Method | Path | 用途 |
| --- | --- | --- |
| `GET` | `/v1/supported/networks` | InfraIO Pay 能結算的所有鏈(主網 + 測試網，依環境過濾)。 |
| `GET` | `/v1/supported/tokens` | 上述鏈上的所有穩定幣。 |
| `GET` | `/v1/supported/currencies` | `order.currency` 接受的幣別。 |

## 健康狀態

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

## Cursor 分頁

每個列表 endpoint 接受相同 query 參數、回傳相同信封。Cursor 為不透明字串，用來取代 offset，
因此在你翻頁時有新資料加入，頁面也不會錯位。

| Query param | 型別 | 預設 | 備註 |
| --- | --- | --- | --- |
| `cursor` | `string` | — | 不透明 — 請逐字複製前次回應的 `next_cursor`。 |
| `limit` | `int` | `20` | `1..100`。 |
| `sort_dir` | `'asc' \| 'desc'` | `desc` | 依 `(created_at, id)` 排序。 |
| `from` / `to` | `RFC3339` | — | 選填的時間視窗過濾。 |
| `search` | `string` | — | 支援的地方做自由文字過濾。 |

回應信封:

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

`has_next` 永遠存在。`next_cursor` 在 `has_next` 為 `false` 時省略。
請把 cursor 視為不透明字串。

## 本頁未涵蓋的部分

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