创建归集
执行支持待确认。 查看适用范围。
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
}