跳到主要内容

归集

接入前请查看接口开放状态,并在目标环境确认账户权限。

操作方法与路径开放状态
列出归集项GET /v1/settlement-items商户路由已确认
创建归集POST /v1/settlements执行支持待确认
查询归集GET /v1/settlements/{id}商户路由已确认
列出归集GET /v1/settlements商户路由已确认
执行支持待确认

创建归集前请确认目标环境已启用归集执行。查询资源或具备商户路由,不表示已经支持资金归集;适用范围见接口开放状态。

商户查询 IPP 归集项,勾选需要归集的项并创建 Settlement,再使用钱包执行平台返回的交易。平台自动识别链上归集结果,无需提交交易哈希。

目前支持 IPP 入款归集。入款必须达到最终确认高度(finalized)后才会出现在归集项列表中;ERC-20 直接转账不属于归集项。

认证、金额、时间、幂等、分页和错误响应遵循商户 API 通用约定。API Key 仅供商户服务端使用;商户前端从自己的服务端获取待执行交易后调用钱包。

SettlementItem 归集项​

每个 SettlementItem 对应一笔实际 IPP 入款。平台为其生成稳定的标识,重复查询、准备失败后重新归集均不会改变该标识。

Attributes​

属性类型说明
idstring归集项标识,创建归集时使用
statusstringavailable、in_progress、settled,见下表
amountstring该项全额归集金额,以 currency 为单位
currencystring稳定币:usdc、usdt
chaininteger所属网络的标准编号(EIP-155 chain ID)
recipient_addressstring归集到账钱包,由原 IPP 入款确定,不可修改
settlement_idstring / null当前关联的归集任务;未关联时为 null
settled_atstring / null归集达到最终确认的时间;未完成时为 null
状态含义
available入款已最终确认,尚未归集且未被任务占用
in_progress已被归集任务占用,尚未完成归集
settled归集已最终确认

准备失败释放占用后,归集项恢复 available,settlement_id 清空。历史任务仍保留所选归集项的 ID。

对象示例​

{
"id": "si_example",
"status": "available",
"amount": "12.5",
"currency": "usdc",
"chain": 8453,
"recipient_address": "0x1234567890abcdef1234567890abcdef12345678",
"settlement_id": null,
"settled_at": null
}

列出归集项​

GET /v1/settlement-items

查询当前商户的归集项,默认返回可归集项。按平台首次确认入款可归集的时间倒序排列,时间相同时按 ID 倒序排列。多个筛选条件同时生效。

Attributes​

属性位置类型必填说明
statusquerystring否available、in_progress、settled;默认 available
chainqueryinteger否按网络编号筛选
currencyquerystring否按稳定币筛选:usdc、usdt
page_sizequeryinteger否每页数量,默认 20,范围 1–100
page_tokenquerystring否上一页返回的 next_page_token;第一页不传

无需 Idempotency-Key,无请求体。翻页时保持筛选条件不变。列表反映查询时的状态,创建归集时仍会重新校验所选项。

请求示例​

GET /v1/settlement-items?status=settled&chain=8453&currency=usdc&page_size=20
Authorization: Bearer inv_test_...

返回示例​

200 OK,返回完整的 SettlementItem 对象数组。

{
"data": [
{
"id": "si_example",
"status": "settled",
"amount": "12.5",
"currency": "usdc",
"chain": 8453,
"recipient_address": "0x1234567890abcdef1234567890abcdef12345678",
"settlement_id": "st_example",
"settled_at": "2026-10-27T08:10:00Z"
}
],
"next_page_token": ""
}

没有匹配记录时返回 {"data":[],"next_page_token":""}。

Settlement 归集任务​

一个 Settlement 对应一次归集,所有选中项通过一笔交易全额归集。创建后,归集项、金额、网络、稳定币和到账钱包均不可修改,不提供取消接口。

Attributes​

属性类型说明
idstring归集任务标识
statusstring归集状态,见下表
item_idsstring[]本次选中的归集项 ID
amountstring所选项的归集金额合计,以 currency 为单位
currencystring稳定币:usdc、usdt
chaininteger所属网络的标准编号(EIP-155 chain ID)
recipient_addressstring归集到账钱包
next_actionobject / null待执行的钱包交易,仅在 requires_action 时返回,其余状态为 null
transaction_hashstring / null平台从链上识别的匹配归集交易哈希;尚未识别时为 null
last_execution_errorobject / null最近一次已确认的错误;无错误时为 null,见下文
created_atstring创建时间
updated_atstring最后更新时间
settled_atstring / null归集达到最终确认的时间;未完成时为 null

状态与交互​

状态含义商户操作
preparing后端正在准备交易,所选项已占用轮询查询任务
requires_action交易已准备好,等待钱包执行或链上识别使用返回的交易调用钱包;发送后轮询查询
processing平台已监听到匹配的归集交易,等待最终确认轮询查询,不重复发送
succeeded本次归集已最终确认归集完成
failed下发可执行交易前准备失败,所选项已释放刷新归集项后,可重新创建任务

正常流程为 preparing → requires_action → processing → succeeded;准备失败时为 preparing → failed。

钱包拒绝签名不会改变任务状态。交易发送后、平台尚未监听到匹配交易时,状态仍为 requires_action;该状态不代表交易尚未发送,商户前端应保留钱包发送结果,避免重复操作。

超时、暂未查到交易或最终确认前发生链上回滚,不作为准备失败处理,不释放归集项。已进入 processing 的任务在结果核实期间保持该状态;平台确认需要商户重新执行时,任务回到 requires_action,并提供更新后的交易。只有归集达到最终确认后才进入 succeeded。

执行交易前应重新查询原任务,使用当前的 next_action。平台可能更新待执行交易,所选归集项、金额、网络、稳定币和到账钱包保持不变。

requires_action 和 processing 持续占用所选归集项。未继续操作的任务不会自动释放占用,商户应继续使用原任务完成归集。

next_action​

属性类型说明
typestring固定为 send_transaction
chain_idinteger钱包执行交易的网络编号,与 Settlement 的 chain 一致
transaction.fromstring执行交易要求使用的钱包地址
transaction.tostring交易目标地址
transaction.datastring0x 开头的十六进制交易调用数据
transaction.valuestring原生币金额,以最小单位表示的十六进制字符串,例如 0x0

商户前端应提示钱包切换至 chain_id,使用指定的 from 执行交易,不修改 to、data 或 value。Gas 相关费用参数由钱包估算。签名和发送由商户钱包完成,平台不代替商户发送交易。

last_execution_error​

属性类型说明
codestring错误码,当前为 transaction_preparation_failed
messagestring可读的错误说明,不作为程序判断依据

此字段仅报告平台已确认的准备失败,不代表平台能够识别钱包拒签、广播失败或所有链上执行失败。

对象示例​

以下地址和调用数据仅用于展示格式,商户应使用接口返回的完整交易。

{
"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
}

创建归集​

POST /v1/settlements

提交选中的归集项 ID。金额、网络、稳定币和到账钱包由平台确定,无需填写。

每次选择 1–100 个不同的归集项,所有项必须为 available,且可通过一笔交易归集至同一钱包。同网络、同稳定币、同钱包是必要条件,但不保证任意组合都能合并归集;无法合并时返回 settlement_items_incompatible,商户需减少或调整所选项。

任一项不存在、不可归集或无法合并时,整批拒绝,不创建任务、不占用任何项。创建成功后,所有选中项立即变为 in_progress。

Attributes​

属性位置类型必填说明
Idempotency-Keyheaderstring是本次操作的唯一键;重试沿用原值
item_idsbodystring[]是归集项 ID,1–100 项,不得重复

请求超时或无法确认创建结果时,使用原幂等键和原参数重试。有效幂等重试返回首次创建结果,任务 ID 不变;最新状态通过查询归集接口获取。

请求示例​

POST /v1/settlements
Authorization: Bearer inv_test_...
Content-Type: application/json
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
{
"item_ids": ["si_example"]
}

返回示例​

200 OK,返回状态为 preparing 的完整 Settlement 对象。

{
"id": "st_example",
"status": "preparing",
"item_ids": ["si_example"],
"amount": "12.5",
"currency": "usdc",
"chain": 8453,
"recipient_address": "0x1234567890abcdef1234567890abcdef12345678",
"next_action": null,
"transaction_hash": null,
"last_execution_error": null,
"created_at": "2026-10-27T08:00:00Z",
"updated_at": "2026-10-27T08:00:00Z",
"settled_at": null
}

查询归集​

GET /v1/settlements/{id}

Attributes​

属性位置类型必填说明
idpathstring是归集任务标识

无需 Idempotency-Key,无请求体。不存在或无权访问时统一返回 404。

请求示例​

GET /v1/settlements/st_example
Authorization: Bearer inv_test_...

返回示例​

200 OK,返回完整 Settlement 对象,格式见对象示例。在 requires_action 时,商户使用该响应中的 next_action 调用钱包。

列出归集​

GET /v1/settlements

查询当前商户的归集任务,按创建时间倒序排列,创建时间相同时按 ID 倒序排列。默认返回全部状态,多个筛选条件同时生效。

Attributes​

属性位置类型必填说明
statusquerystring否preparing、requires_action、processing、succeeded、failed
chainqueryinteger否按网络编号筛选
currencyquerystring否按稳定币筛选:usdc、usdt
page_sizequeryinteger否每页数量,默认 20,范围 1–100
page_tokenquerystring否上一页返回的 next_page_token;第一页不传

无需 Idempotency-Key,无请求体。翻页时保持筛选条件不变。

请求示例​

GET /v1/settlements?status=succeeded&page_size=20
Authorization: Bearer inv_test_...

返回示例​

200 OK,data 中的每一项均为完整的 Settlement 对象。

{
"data": [
{
"id": "st_example",
"status": "succeeded",
"item_ids": ["si_example"],
"amount": "12.5",
"currency": "usdc",
"chain": 8453,
"recipient_address": "0x1234567890abcdef1234567890abcdef12345678",
"next_action": null,
"transaction_hash": "0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"last_execution_error": null,
"created_at": "2026-10-27T08:00:00Z",
"updated_at": "2026-10-27T08:10:00Z",
"settled_at": "2026-10-27T08:10:00Z"
}
],
"next_page_token": ""
}

没有匹配记录时返回 {"data":[],"next_page_token":""}。

业务错误码​

HTTP 状态码code含义
404settlement_not_found归集任务不存在或无权访问
404settlement_item_not_found所选归集项不存在或无权访问
409settlement_item_unavailable所选项已被占用或已归集;刷新列表后重新选择
400settlement_items_incompatible所选项无法通过一笔交易归集;调整所选项

空数组、重复 ID、超过数量上限或无效筛选值返回 400 参数错误。准备失败发生在创建成功之后,通过 Settlement 的状态和 last_execution_error 返回,不改变首次创建请求的成功结果。