Facilitator HTTP 接入
本页说明自建或运营方提供的原生 Facilitator HTTP 接口。InvisiPay 托管 商户接入使用商业支付文档。HTTP 消息展示完整请求格式;curl 示例会访问指定服务,但不会执行资金操作。https://facilitator.example、所有 EXAMPLE 值与地址是占位值;替换为运营方地址、有效 Key、启用的资产和未来截止时间。base_usdc 必须是实际发布选项;示例不证明 Base 上已有可用服务。
1. 商户创建会话
服务端配置商户 Key(inv_test_ 或 inv_live_ 前缀),从已认证订单生成请求。同一次订单重试保持同一 Idempotency-Key 和语义输入。前缀不决定链或最终性。不要把商户 Key 交给钱包或浏览器。
POST /v1/checkouts HTTP/1.1
Host: facilitator.example
Authorization: Bearer inv_test_EXAMPLE_MERCHANT_KEY
Content-Type: application/json
Accept: application/json
Idempotency-Key: order-EXAMPLE-001
{
"ippVersion": 1,
"mode": "payment",
"description": "Research report",
"options": [{
"id": "base_usdc",
"method": "invisi",
"network": "eip155:8453",
"asset": {
"address": "0x1111111111111111111111111111111111111111",
"symbol": "USDC",
"decimals": 6
},
"amount": "10000000"
}],
"expiresAt": "2026-12-18T08:05:00Z"
}
首次成功返回 201,相同创建重放返回 200;不同输入重用键返回 409。下列启动响应不含单独的 sessionId,先读取 sessionUrl 获取:
{
"ippVersion": 1,
"type": "checkout",
"sessionUrl": "https://facilitator.example/v1/sessions/ses_EXAMPLE",
"checkoutUrl": "https://dapp.invisipay.fi/checkout#sessionUrl=https%3A%2F%2Ffacilitator.example%2Fv1%2Fsessions%2Fses_EXAMPLE&token=EXAMPLE_SESSION_TOKEN",
"expiresAt": "2026-12-18T08:05:00Z"
}
商户保存原入口与订单关联,经受信通道交付 checkoutUrl。Token 位于收银台 fragment,调用 API 时改用 Bearer。服务端查询也可使用所属商户 Key,避免把客户端 JSON 当作付款结论。
2. 钱包读取并确认
以下只读调用使用创建返回的原 sessionUrl。按原样使用返回的完整 URL,不要自行添加或推测路径。
curl --fail-with-body --silent --show-error \
'https://facilitator.example/v1/sessions/ses_EXAMPLE' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer EXAMPLE_SESSION_TOKEN'
核对 merchant 展示、真实服务 origin、mode 和 options。确认前 links.request 为 null;通过响应的 links.confirm.href 及其 method 操作,示例假设它恰好为以下地址:
POST /v1/sessions/ses_EXAMPLE/confirm HTTP/1.1
Host: facilitator.example
Authorization: Bearer EXAMPLE_SESSION_TOKEN
Content-Type: application/json
Accept: application/json
Idempotency-Key: confirm-EXAMPLE-001
{"optionId":"base_usdc"}
首次返回 201 与完整 PaymentRequest/CreditRequest,Location 给出读取地址;重放返回 200 与原 Request。保留 Location 和原 sessionUrl。只有首次确认产生新材料;同选项重试恢复原材料,不同选项冲突。商户 API Key 不能替代此处 Session Token。
3. 执行、查询和履约
按付款或授信规则核对完整 Request,再由钱包授权执行。可选 Credential 提交至 Request.links.credentials,202 不表示成功。后台即使没有 Credential 或查询也持续验证。
复用上面的 GET 查询会话;HTTP 200 表示读取成功,业务上可能仍 processing 或 failed。成功时应有 receipt,商户检查 status=succeeded、当前 evidenceStatus 与业务条款,并以本地订单为幂等边界履约。纯授信成功只表示授权建立。
收费 API 可以先创建或复用 Checkout,返回 402 和标准 PaymentSession,并使用 Link 的 ipp-session/ipp-checkout 关系交付同一入口。支付后客户端按商户 API 的约定重试原业务操作,商户验证调用者及原始收费参数、认证查询自己的会话、恢复或返回原业务结果。客户端提供的引用不构成领取权限,不能无限复用一次付款。
端点与访问恢复
| Method | Route | Authorization |
|---|---|---|
| POST | /v1/checkouts | Merchant API Key |
| GET | /v1/checkouts/{sessionId} | Owning merchant API Key |
| POST | /v1/checkouts/{sessionId}/access | Owning merchant API Key |
| GET | /v1/checkouts/{sessionId}/exceptions | Owning merchant API Key |
| GET | /v1/sessions/{sessionId} | Session Token or owning merchant API Key |
| POST | /v1/sessions/{sessionId}/confirm | Session Token |
| GET | /v1/sessions/{sessionId}/requests/{requestId} | Session Token |
| POST | /v1/sessions/{sessionId}/requests/{requestId}/credentials | Session Token |
表中的商户管理端点属于 Facilitator 扩展;需要兼容不同服务的付款客户端应跟随完整 IPP links。access 使用无请求体的 POST,返回带替换 Token 的 Checkout 并使旧 Token 失效,保持原材料和截止。exceptions 返回 {"data":[...]},内容是已验证异常事实,不暴露共享密钥或解密状态,也不自动完成退款。
创建 Idempotency-Key 为 1–128 个无空白可打印 ASCII 字符;请求体上限 64 KiB,选项最多 100 个。未知字段、重复属性和不规范编码被拒绝。遵循 Retry-After;响应含 Request-Id,便于运营方定位请求。不要记录 Authorization、收银台 fragment 或完整私密 Request。
授权、截止与恢复解释错误与安全重试。IPP 没有独立 Receipt 查询或手动核销步骤。