跳到主要内容

创建归集

执行支持待确认。 查看适用范围。

对象与完整字段 · 认证、金额与错误 · 接入指南

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
}

业务错误码