归集 IPP 入款并对账
归集项列表及任务查询已有商户接口,创建归集的执行能力仍待确认。使用本流程前,确认目标环境支持归集创建和钱包执行,且账户已获准使用。参阅接口可用性。
Settlement 把已收到的 IPP 资金全额归集到原入款固定的钱包。签名和发送由商户钱包完成,平台准备交易并自动识别结果。这是自托管资金归集,不是银行出款,也不能任意更改到账钱包。
仅 finalized 的 IPP 入款进入 SettlementItem 列表;直接 ERC-20 转账不属于归集项。入款完成、资金可归集及归集最终完成是三个不同事实,业务履约和资金管理分别对账。
准备服务端参数
Key 仅供商户服务端调用。将示例值替换为实际测试 Key、API 返回的 Settlement ID 及 available item ID。每个新任务使用独立且持久化的幂等键,重试保留原值。开始前确认测试环境支持本流程所需操作。
export API_BASE='https://connect-dev.invisipay.fi'
export API_KEY='inv_test_REPLACE_WITH_YOUR_SERVER_KEY'
export SETTLEMENT_ID='st_REPLACE_WITH_CREATED_SETTLEMENT_ID'
export SETTLEMENT_CREATE_KEY='a4a0df47-d4d5-4e6b-9fd4-d296f8866cf1'
1. 列出并选择归集项
curl --fail-with-body --silent --show-error --get \
"$API_BASE/v1/settlement-items" \
-H "Authorization: Bearer $API_KEY" \
--data-urlencode 'status=available' \
--data-urlencode 'chain=8453' \
--data-urlencode 'currency=usdc' \
--data-urlencode 'page_size=20'
接口默认返回 available;可按网络、币种和状态筛选。分页沿用 next_page_token,翻页保持筛选不变。下面是一个归集项示例,不含分页包装:
{
"id": "si_example",
"status": "available",
"amount": "12.5",
"currency": "usdc",
"chain": 8453,
"recipient_address": "0x1234567890abcdef1234567890abcdef12345678",
"settlement_id": null,
"settled_at": null
}
选 1–100 个不同的 available 项。同网络、同币种、同 recipient_address 是必要条件,仍可能无法合为一笔交易;这时返回 settlement_items_incompatible,应减少或调整选择。任何一项无效都会整批拒绝,不创建任务或占用其他项。
每项使用币种单位十进制 amount,归集是全额操作,不提交自定义金额,不做浮点换算或舍入。Settlement.amount 是选中项合计;不要把 API 中的 "12.5" 当成链上 calldata 的整数金额。recipient_address 由原 IPP 入款决定,创建请求不接受另指定钱包。
2. 创建并保存任务
curl --fail-with-body --silent --show-error \
"$API_BASE/v1/settlements" \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-H "Idempotency-Key: $SETTLEMENT_CREATE_KEY" \
--data '{"item_ids":["si_REPLACE_WITH_AVAILABLE_ITEM_ID"]}'
HTTP 200 返回 preparing 的完整 Settlement。保存任务 ID、选中 item_ids 与本地资金记录;这些项立即被占用为 in_progress。金额、网络、币种、到账钱包和所选项创建后不可修改,没有取消接口。
超时或崩溃后用原键与原 item_ids 重试。有效幂等重放返回首次创建结果与相同任务 ID,最新状态通过 GET 获取。24 小时幂等窗口后先核对原任务,不因查询或广播超时另建任务。
3. 读取当前钱包操作
curl --fail-with-body --silent --show-error \
"$API_BASE/v1/settlements/$SETTLEMENT_ID" \
-H "Authorization: Bearer $API_KEY"
preparing 期间轮询。requires_action 时由商户服务端把当前 next_action 交给已认证商户前端,再调用钱包。下方是完整示例任务,地址和 calldata 仅展示格式,不能直接执行:
{
"id": "st_example",
"status": "requires_action",
"item_ids": ["si_example"],
"amount": "12.5",
"currency": "usdc",
"chain": 8453,
"recipient_address": "0x1234567890abcdef1234567890abcdef12345678",
"next_action": {
"type": "send_transaction",
"chain_id": 8453,
"transaction": {
"from": "0x1234567890abcdef1234567890abcdef12345678",
"to": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
"data": "0x12345678",
"value": "0x0"
}
},
"transaction_hash": null,
"last_execution_error": null,
"created_at": "2026-10-27T08:00:00Z",
"updated_at": "2026-10-27T08:00:01Z",
"settled_at": null
}
签名前重新 GET 原任务;平台可能更新交易,但不会改选中项、金额、网络、币种和到账钱包。提示钱包切换到 next_action.chain_id,并使用 transaction.from 对应账户。原样传递 to、data、value,Gas 相关参数由钱包估算;value 是原生币最小单位的十六进制字符串,不是币种十进制 amount。
商户钱包自行签名和发送,平台不代签或代发。保留钱包返回的交易哈希和原任务 ID。平台自动识别匹配交易,不需要商户提交哈希的确认接口。
4. 等待最终结果并恢复
| status | 处理方式 |
|---|---|
| preparing | 继续查询,所选项已占用 |
| requires_action | 使用最新 next_action;若已经发送,先核对原交易,不据此重复发送 |
| processing | 已发现匹配交易,等待 finalized;不重发、不新建任务 |
| succeeded | 归集已最终确认,归集项为 settled;记录 transaction_hash、settled_at |
| failed | 下发可执行交易前准备失败,项已释放;刷新后可创建新任务 |
拒签不改变状态。发送后尚未被平台观察到时也可能保持 requires_action。超时、暂查不到或最终确认前回滚不是准备失败,不释放占用。processing 保持到结果核实;只有平台明确回到 requires_action 并提供新交易时,才准备再次执行。
last_execution_error 当前仅报告 transaction_preparation_failed,不能据此假定平台识别所有钱包、广播和链上失败。requires_action/processing 长期未操作也不会自动释放项,应继续原任务,不等待自动取消。
5. 对账已完成归集
curl --fail-with-body --silent --show-error --get \
"$API_BASE/v1/settlements" \
-H "Authorization: Bearer $API_KEY" \
--data-urlencode 'status=succeeded' \
--data-urlencode 'page_size=20'
关联任务 ID、item_ids、原入款、amount、网络、币种及到账钱包;以 succeeded 和 settled_at 记录完成。无匹配记录返回空 data,next_page_token 为空字符串表示结束。历史准备失败任务保留 item_ids,但项释放后 settlement_id 会清空,不能按旧关联误判已完成。
遇到 settlement_item_unavailable 先刷新库存;settlement_items_incompatible 则调整组合。HTTP 参数错误与已受理任务之后的准备失败分开处理。全部字段、分页、状态和错误见归集 API。