创建并确认第一笔收款
本指南通过创建、查询 Checkout 完成第一笔收款,不依赖 Webhook。开始前确认测试账户已具备创建和查询权限,支持范围见接口开放状态。下列请求使用测试环境地址,所有 Key、订单与响应值均需替换为你的测试数据。
1. 准备服务端
需要 curl、测试 API Key 和能够持久化订单与付款尝试的服务端。下面环境变量只用于演示;生产应用应从密钥管理系统读取 Key,从数据库读取已保存的幂等键。
export API_BASE='https://connect-dev.invisipay.fi'
export API_KEY='inv_test_REPLACE_WITH_YOUR_SERVER_KEY'
export CHECKOUT_CREATE_KEY='550e8400-e29b-41d4-a716-446655440000'
每次新操作生成新幂等键,重试原操作时保留原键及原参数。先在事务中记录订单、预期金额、币种、请求体及幂等键,再发送创建请求;API Key 不放进网页或移动客户端。
2. 查询可用收款方式
curl --fail-with-body --silent --show-error \
"$API_BASE/v1/payment-methods" \
-H "Authorization: Bearer $API_KEY"
ipp(IPP 收款)与 erc20_transfer(直接 ERC-20 转账)是两种收款方式;响应按方式分组,每项是该方式支持的完整币种/网络组合。只使用接口实际返回的组合,不自行组合币种与网络。完整格式见收款方式。
后续示例使用 USDC;继续前确认返回列表中至少有一个支持 usdc 的收款方式及网络组合。若没有,请先确认账户支持范围,或按订单实际支持的币种调整金额与请求。
3. 创建 Checkout
Checkout 是一次收款会话。订单金额由服务端可信订单数据决定,不接受前端直接覆盖价格。"10" 表示 10 USDC,不是最小单位。
curl --fail-with-body --silent --show-error \
"$API_BASE/v1/checkouts" \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-H "Idempotency-Key: $CHECKOUT_CREATE_KEY" \
--data '{"amount":"10","currency":"usdc","order_id":"ORDER_001","description":"Order payment"}'
以下是响应片段,ID 与 URL 为演示值,不可用于真实查询或收款:
{
"id": "checkout_example",
"amount": "10",
"currency": "usdc",
"order_id": "ORDER_001",
"status": "open",
"exception_status": null,
"url": "https://pay.example.com/c/checkout_example"
}
保存返回的 id、url 与本地付款尝试的关联。同一订单可能产生多次 Checkout;不要把非唯一的 order_id 当成接口去重保证。参数、必填项与返回字段见创建 Checkout。
4. 交付收银台链接
把真实响应的 url 交付当前订单的付款人。return_url 只是收银台“返回商户”按钮的目标,不是付款证明,也不保证自动跳转。付款人访问你的订单页时,应先认证其访问权限,再查询本地订单关联的 Checkout。
5. 查询并确认
下面假设已把 CHECKOUT_ID 替换成实际响应 ID;示例 ID 无保留字符,通用客户端需对路径 ID 编码。
export CHECKOUT_ID='REPLACE_WITH_THE_RETURNED_CHECKOUT_ID'
curl --fail-with-body --silent --show-error \
"$API_BASE/v1/checkouts/$CHECKOUT_ID" \
-H "Authorization: Bearer $API_KEY"
| 返回情况 | 业务动作 |
|---|---|
open | 显示等待付款,由服务端按限流策略继续查询 |
processing | 付款已上链、确认中;展示进度,不引导重复付款 |
succeeded 且订单、币种、金额一致 | 结合异常状态,按订单执行一次履约 |
failed | 停止将此会话当成可成功的收款入口,按失败原因处理 |
存在 exception_status | 独立处理资金异常,不凭主状态抹除异常 |
| 请求超时或 HTTP 错误 | 原订单结果未知;恢复查询,不直接重新收款 |
完整状态见支付状态与异常。确认与履约的可复用服务端示例见查询确认与幂等履约。
6. 测试后再扩展能力
验证重复点击、创建超时、应用重启及同订单多次 Checkout 都不会重复发货。Webhook 开放后再接入验签与事件处理,并保留查询补偿。退款与归集分别遵循各自的开放状态,不能从收款接口可调用推导它们已可用。