Skip to Content
API 参考概览

API 参考

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

本页是索引。每一行链接到最深层已存在的说明;如果某行只引用一个路径, 说明该端点今天已存在,但记录在相关概念页内联文档中,而不是它自己的 参考页。

Gateway 路径前缀及其鉴权模型:

  • /b2b/v1/* — 使用你的 secret key(sk_…)进行 HMAC 签名。 商户后端表面。
  • /payment/v1/* — Bearer JWT(仪表板会话)。由商户仪表板前端 使用;不面向第三方集成方。
  • /pub/v1/* — 真相载体在路径上(退款申请的 rfqt_… token)。 无凭据。可安全从浏览器调用。
  • /checkout/:key/* — 托管结账流程的公共前缀。key 是创建时 返回的 cst_… session_key;唯一调用方是买家的浏览器。无凭据。

结账

方法路径用途备注
POST/b2b/v1/checkout-sessions/quick一次调用创建会话 — 订单 + 结账会话一并铸造。请求 body 与示例见 快速入门。
POST/b2b/v1/checkout-sessions针对已存在订单创建会话。当你的平台已有自己的订单模型,且希望每次尝试一个会话时使用。两步流程。
GET/b2b/v1/checkout-sessions/by-order/{order_id}列出某订单曾铸造的所有会话。当买家放弃了一次会话,且你想在自己的仪表板呈现历次尝试时有用。
GET/checkout/{session_key}公共 — 托管结账页读取此端点。仅面向买家的字段(无内部引用)。无签名;以 session_key 作为真相载体。
POST/checkout/{session_key}/intent公共 — 在托管页选择一种支付方式。发出 PaymentIntent,带充值地址。checkout-web 在用户选择方式时调用。
POST/checkout/{session_key}/verify公共 — 允许买家粘贴一个 tx hash 以缩短等待确认的时间。哈希错误时回落到链上观察者。

订单

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

方法路径用途备注
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 交付。两条 铸造路径(B2B 用 HMAC,仪表板用 JWT),三条公共 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)。
POST/payment/v1/merchants/{merchant_id}/refund-requestsJWT(仪表板)从商户仪表板的 Issue Refund 弹窗铸造 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}/submitToken 在路径公共 — 买家提交表单。Body:{reason, refund_to_address, amount?, metadata?}。amount 可选 — 省略时使用商户锁定的链接金额;提供时服务端强制 amount ≤ 锁定金额。创建 Refund 行、发出 payment.refund.requested、为收据页返回 {link_token, refund_id}。
POST/pub/v1/refund-requests/{token}/request-renewalToken 在路径公共 — 买家在过期后申请一个新的链接。Body:{customer_note?}。发出 refund_request.renewal_requested。
GET/payment/v1/merchants/{merchant_id}/refund-requests/renewalsJWT(仪表板)列出该商户续期组件中处于 RENEWAL_REQUESTED 的待审 token。Cursor 分页。
POST/payment/v1/merchants/{merchant_id}/refund-requests/renewals/{token}/issue-newJWT(仪表板)批准续期 — 铸造新的 ACTIVE token,作废旧的。发出 refund_request.renewed + refund_request.created(source: renewal)。
GET/payment/v1/merchants/{merchant_id}/refund-requests/by-order/{order_id}JWT(仪表板)列出针对某订单曾经铸造过的所有退款申请 token,附有效状态。按时间倒序。
POST/payment/v1/merchants/{merchant_id}/refund-requests/{token}/send-emailJWT(仪表板)把退款申请链接通过邮件投递给客户排队发送。Body:{to}。发出 refund_request.email_send_requested。
POST/payment/v1/merchants/{merchant_id}/refund-requests/{token}/cancelJWT(仪表板)商户终止开关 — 把 ACTIVE 或 RENEWAL_REQUESTED 翻转为 CANCELED。Body:{reason?}。幂等:状态已迁移后第二次调用返回成功且不重复发事件。首次迁移发出 refund_request.canceled。

退款生命周期(创建后)

适用于两种流程。下面这些端点操作的是 Refund 行(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 可结算的全部链(主网 + 测试网,按环境筛选)。
GET/v1/supported/tokens这些链上的稳定币。
GET/v1/supported/currenciesorder.currency 接受的法币货币。
GET/v1/merchants/payment-methods该商户启用了哪些方式 — 平台目录 + 每商户开关的合集。checkout-web 使用。
GET/v1/public/merchants/{merchant_id}/branding公共 — 结账页读取它来给自己换肤。

健康

方法路径鉴权用途
GET/health无(公开)纯存活探测 — 返回 {"status":"ok"}。这个(没有 /v1 前缀)是唯一无需鉴权的健康端点 — 把你的 k8s / 在线监控指向这里。
GET/payment/v1/merchants/{merchant_id}/health仪表板 JWT每商户的健康视图 — 近期 intent 结算率、归集积压。适合你自己的状态页。需要仪表板会话 token,不是 B2B API key。只能在 /payment/ 这个 gateway 前缀下访问 —— 裸 /v1/... 路径未对外路由。
GET/payment/v1/stats/health仪表板 JWT跨商户工作区树的聚合健康。不是公开的存活探测 — 它和 /payment/ 前缀下 /v1/* 其余部分一样位于相同的 JWT 鉴权之后。

Cursor 分页

每个 list 端点接受相同的查询参数,返回相同的信封。我们使用不透明 cursor(base64url 编码的 (created_at, id))而不是 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 — 它的形态是内部细节,会变化。

本页未涵盖

本索引覆盖商户向外的表面 — /admin/* 下的端点(仪表板工具、KYB 审核、 网络管理)和内部 gRPC 路由有意未列出。swag 生成的 OpenAPI 规范覆盖 完整表面;如有需要,联系支持团队,我们会分享当前快照。

JavaScript / 浏览器身份验证