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

# API 参考

下方每个端点都讲 JSON,部署在 `https://api.infraio.xyz`(生产)
或 `https://api-dev.infraio.xyz`(测试),并通过 HMAC-SHA256 鉴权 —
请求签名见 [身份验证](https://docs.infraio.xyz/zh-CN/api-reference/authentication),错误信封
形态见 [错误](https://docs.infraio.xyz/zh-CN/api-reference/errors)。

本页列出面向商户集成的端点。没有独立页面的端点,会在相关概念页中说明。

> **Note:**
>
> **`/b2b/v1/*`** 下的端点使用你的 **secret** key(`sk_…`)进行 HMAC 签名,
> 这是你的后端调用的表面。商户仪表板和托管收银台使用各自的端点,
> 不属于集成 API。

## 结账

| 方法 | 路径 | 用途 | 备注 |
| --- | --- | --- | --- |
| `POST` | `/b2b/v1/checkout-sessions/quick` | 一次调用创建会话 — 订单 + 结账会话一并铸造。 | 请求 body 与示例见 [快速入门](https://docs.infraio.xyz/zh-CN/get-started/quickstart#2-创建结账会话服务端)。 |
| `POST` | `/b2b/v1/checkout-sessions` | 针对*已存在*订单创建会话。当你的平台已有自己的订单模型,且希望每次尝试一个会话时使用。 | 两步流程。 |
| `GET` | `/b2b/v1/checkout-sessions/by-order/{order_id}` | 列出某订单曾铸造的所有会话。 | 当买家放弃了一次会话,且你想在自己的仪表板呈现历次尝试时有用。 |

## 订单

订单是恒定的可计费实体。一个订单可以背靠多个结账会话(例如买家放弃后重试)。

| 方法 | 路径 | 用途 | 备注 |
| --- | --- | --- | --- |
| `POST` | `/b2b/v1/orders` | 不带会话创建订单。 | 当你想稍后给买家发支付链接而不是立即跳转时使用。 |
| `GET` | `/b2b/v1/orders/{id}` | 读取单个订单,含明细项 + 状态。 | 状态:`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 生命周期见 [退款概念页](https://docs.infraio.xyz/zh-CN/concepts/refunds)。

### 商户发起

| 方法 | 路径 | 用途 | 备注 |
| --- | --- | --- | --- |
| `POST` | `/b2b/v1/merchants/{merchant_id}/refunds` | 商户发起的退款。自动批准(跳过 `PENDING`)。 | 立即发出 `payment.refund.approved`。 |

### 客户发起 — 退款申请 token

买家在我们托管页填退款表单;你只负责铸造 token 并把 URL 交付。你可以
从后端(见下)或商户仪表板铸造 token。续期与取消在仪表板中处理。

| 方法 | 路径 | 鉴权 | 用途 |
| --- | --- | --- | --- |
| `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`)。 |

### 退款生命周期(创建后)

适用于两种流程。下面这些端点操作的是退款本身(id 以 `rfn_…` 开头),
不是申请 token。

| 方法 | 路径 | 用途 | 备注 |
| --- | --- | --- | --- |
| `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}` — 三者必填。 |

## 目录(只读)

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| `GET` | `/v1/supported/networks` | InfraIO Pay 可结算的全部链(主网 + 测试网,按环境筛选)。 |
| `GET` | `/v1/supported/tokens` | 这些链上的稳定币。 |
| `GET` | `/v1/supported/currencies` | `order.currency` 接受的货币。 |

## 健康

| 方法 | 路径 | 鉴权 | 用途 |
| --- | --- | --- | --- |
| `GET` | `/health` | 无(公开) | 存活检查。返回 `{"status":"ok"}`。请将在线监控指向这里。 |

## Cursor 分页

每个 list 端点接受相同的查询参数,返回相同的信封。cursor 不透明,且使用它而不是 offset,这样
当翻页时有新行到达,页面也不会偏移。

| 查询参数 | 类型 | 默认 | 备注 |
| --- | --- | --- | --- |
| `cursor` | `string` | — | 不透明 — 把上一次响应里的 `next_cursor` 原样复制。 |
| `limit` | `int` | `20` | `1..100`。 |
| `sort_dir` | `'asc' \| 'desc'` | `desc` | 按 `(created_at, id)` 排序。 |
| `from` / `to` | `RFC3339` | — | 可选的时间窗筛选。 |
| `search` | `string` | — | 在支持的端点上做自由文本筛选。 |

响应信封:

```json
{
  "orders": [ /* 当前页的行 */ ],
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNS0...",
  "has_next": true
}
```

`has_next` 永远存在。当 `has_next` 为 `false` 时,`next_cursor` 省略。
请把 cursor 当作不透明字符串。

## 本页未涵盖

本页涵盖面向商户集成的端点。如果你需要未列出的端点或 OpenAPI 规范,
请联系支持团队。