Skip to Content
API 参考概览
View as Markdown

API 参考

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

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

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

结账

方法路径用途备注
POST/b2b/v1/checkout-sessions/quick一次调用创建会话 — 订单 + 结账会话一并铸造。请求 body 与示例见 快速入门。
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 分页。
PATCH/b2b/v1/orders/{id}/cancel把未支付订单标记为取消。发出 order.canceled。已支付订单会失败。
PATCH/b2b/v1/orders/{id}/reopen反向操作自动取消(canceled_reason=payment_timeout)。当买家在 TTL 过期后回来时有用。

退款

saga 流程与 token 生命周期见 退款概念页。

商户发起

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

客户发起 — 退款申请 token

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

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

退款生命周期(创建后)

适用于两种流程。下面这些端点操作的是退款本身(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/networksInfraIO Pay 可结算的全部链(主网 + 测试网,按环境筛选)。
GET/v1/supported/tokens这些链上的稳定币。
GET/v1/supported/currenciesorder.currency 接受的货币。

健康

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

Cursor 分页

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

查询参数类型默认备注
cursorstring—不透明 — 把上一次响应里的 next_cursor 原样复制。
limitint201..100。
sort_dir'asc' | 'desc'desc按 (created_at, id) 排序。
from / toRFC3339—可选的时间窗筛选。
searchstring—在支持的端点上做自由文本筛选。

响应信封:

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

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

本页未涵盖

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

JavaScript / 浏览器身份验证