归集
接入前请查看接口开放状态,并在目标环境确认账户权限。
| 操作 | 方法与路径 | 开放状态 |
|---|---|---|
| 列出归集项 | 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
| 属性 | 类型 | 说明 |
|---|---|---|
id | string | 归集项标识,创建归集时使用 |
status | string | available、in_progress、settled,见下表 |
amount | string | 该项全额归集金额,以 currency 为单位 |
currency | string | 稳定币:usdc、usdt |
chain | integer | 所属网络的标准编号(EIP-155 chain ID) |
recipient_address | string | 归集到账钱包,由原 IPP 入款确定,不可修改 |
settlement_id | string / null | 当前关联的归集任务;未关联时为 null |
settled_at | string / 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
| 属性 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
status | query | string | 否 | available、in_progress、settled;默认 available |
chain | query | integer | 否 | 按网络编号筛选 |
currency | query | string | 否 | 按稳定币筛选:usdc、usdt |
page_size | query | integer | 否 | 每页数量,默认 20,范围 1–100 |
page_token | query | string | 否 | 上一页返回的 next_page_token;第一页不传 |
无需 Idempotency-Key,无请求体。翻页时保持筛选条件不变。列表反映查询时的状态,创建归集时仍会重新校验所选项。
请求示例
GET /v1/settlement-items?status=settled&chain=8453¤cy=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
| 属性 | 类型 | 说明 |
|---|---|---|
id | string | 归集任务标识 |
status | string | 归集状态,见下表 |
item_ids | string[] | 本次选中的归集项 ID |
amount | string | 所选项的归集金额合计,以 currency 为单位 |
currency | string | 稳定币:usdc、usdt |
chain | integer | 所属网络的标准编号(EIP-155 chain ID) |
recipient_address | string | 归集到账钱包 |
next_action | object / null | 待执行的钱包交易,仅在 requires_action 时返回,其余状态为 null |
transaction_hash | string / null | 平台从链上识别的匹配归集交易哈希;尚未识别时为 null |
last_execution_error | object / null | 最近一次已确认的错误;无错误时为 null,见下文 |
created_at | string | 创建时间 |
updated_at | string | 最后更新时间 |
settled_at | string / 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
| 属性 | 类型 | 说明 |
|---|---|---|
type | string | 固定为 send_transaction |
chain_id | integer | 钱包执行交易的网络编号,与 Settlement 的 chain 一致 |
transaction.from | string | 执行交易要求使用的钱包地址 |
transaction.to | string | 交易目标地址 |
transaction.data | string | 0x 开头的十六进制交易调用数据 |
transaction.value | string | 原生币金额,以最小单位表示的十六进制字符串,例如 0x0 |
商户前端应提示钱包切换至 chain_id,使用指定的 from 执行交易,不修改 to、data 或 value。Gas 相关费用参数由钱包估算。签名和发送由商户钱包完成,平台不代替商户发送交易。
last_execution_error
| 属性 | 类型 | 说明 |
|---|---|---|
code | string | 错误码,当前为 transaction_preparation_failed |
message | string | 可读的错误说明,不作为程序判断依据 |
此字段仅报告平台已确认的准备失败,不代表平台能够识别钱包拒签、广播失败或所有链上执行失败。
对象示例
以下地址和调用数据仅用于展示格式,商户应使用接口返回的完整交易。
{
"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-Key | header | string | 是 | 本次操作的唯一键;重试沿用原值 |
item_ids | body | string[] | 是 | 归集项 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
| 属性 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
id | path | string | 是 | 归集任务标识 |
无需 Idempotency-Key,无请求体。不存在或无权访问时统一返回 404。
请求示例
GET /v1/settlements/st_example
Authorization: Bearer inv_test_...
返回示例
200 OK,返回完整 Settlement 对象,格式见对象示例。在 requires_action 时,商户使用该响应中的 next_action 调用钱包。
列出归集
GET /v1/settlements
查询当前商户的归集任务,按创建时间倒序排列,创建时间相同时按 ID 倒序排列。默认返回全部状态,多个筛选条件同时生效。
Attributes
| 属性 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
status | query | string | 否 | preparing、requires_action、processing、succeeded、failed |
chain | query | integer | 否 | 按网络编号筛选 |
currency | query | string | 否 | 按稳定币筛选:usdc、usdt |
page_size | query | integer | 否 | 每页数量,默认 20,范围 1–100 |
page_token | query | string | 否 | 上一页返回的 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 | 含义 |
|---|---|---|
404 | settlement_not_found | 归集任务不存在或无权访问 |
404 | settlement_item_not_found | 所选归集项不存在或无权访问 |
409 | settlement_item_unavailable | 所选项已被占用或已归集;刷新列表后重新选择 |
400 | settlement_items_incompatible | 所选项无法通过一笔交易归集;调整所选项 |
空数组、重复 ID、超过数量上限或无效筛选值返回 400 参数错误。准备失败发生在创建成功之后,通过 Settlement 的状态和 last_execution_error 返回,不改变首次创建请求的成功结果。