Settlement items and settlements API
Check API availability and confirm access in your target environment before integrating.
| Operation | Method and route | Availability |
|---|---|---|
| List settlement items | GET /v1/settlement-items | Merchant route confirmed |
| Create a settlement | POST /v1/settlements | Execution support pending |
| Retrieve a settlement | GET /v1/settlements/{id} | Merchant route confirmed |
| List settlements | GET /v1/settlements | Merchant route confirmed |
Settlement creation execution remains pending confirmation. Verify settlement execution is enabled for your account and environment; see API availability.
List IPP collection items, select items and create a Settlement, then execute the returned transaction using the merchant wallet. The platform recognizes the on-chain result automatically; no transaction-hash submission is required. Settlement is self-custodial collection to the wallet fixed by the original IPP receipt, not a bank payout or arbitrary destination transfer.
Only IPP receipts are supported. They appear as items after finalized confirmation. Direct ERC-20 transfers are outside settlement items.
Authentication, amounts, times, idempotency, pagination and errors follow common conventions. API Keys stay on the merchant server. A merchant frontend obtains the transaction from its server and invokes the wallet.
SettlementItem
Each SettlementItem represents one actual IPP receipt. Its platform-generated identifier remains stable across repeated reads and a new collection attempt after preparation failure.
Attributes
| Attribute | Type | Description |
|---|---|---|
id | string | Settlement item identifier used when creating a Settlement |
status | string | available, in_progress or settled |
amount | string | Full collection amount in currency units |
currency | string | Stablecoin: usdc or usdt |
chain | integer | EIP-155 network ID |
recipient_address | string | Destination wallet fixed by the original IPP receipt; immutable |
settlement_id | string / null | Currently associated task; null if unassociated |
settled_at | string / null | Time collection reached finalized confirmation; null until complete |
| Status | Meaning |
|---|---|
available | Receipt finalized, uncollected and unreserved |
in_progress | Reserved by a collection task that has not completed |
settled | Collection finalized |
Preparation failure releases the reservation, restores available and clears settlement_id. The historical Settlement retains the selected item IDs.
Item example
{
"id": "si_example",
"status": "available",
"amount": "12.5",
"currency": "usdc",
"chain": 8453,
"recipient_address": "0x1234567890abcdef1234567890abcdef12345678",
"settlement_id": null,
"settled_at": null
}
List settlement items
GET /v1/settlement-items
List the current merchant's items, defaulting to available. Sort by descending time first recognized as collectible, then descending ID. Multiple filters apply together.
| Attribute | Location | Type | Required | Description |
|---|---|---|---|---|
status | query | string | No | available, in_progress or settled; default available |
chain | query | integer | No | Filter by network ID |
currency | query | string | No | usdc or usdt |
page_size | query | integer | No | Default 20; range 1–100 |
page_token | query | string | No | Prior next_page_token; omit on first page |
No Idempotency-Key or body is required. Preserve filters when paginating. Results reflect query-time state; creation revalidates every selected item.
Request:
GET /v1/settlement-items?status=settled&chain=8453¤cy=usdc&page_size=20
Authorization: Bearer inv_test_...
Response: 200 OK, complete SettlementItem objects:
{
"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": ""
}
No matches returns {"data":[],"next_page_token":""}.
Settlement
A Settlement collects all selected items in full through one transaction. Items, amount, network, stablecoin and destination wallet become immutable after creation. There is no cancellation endpoint.
Attributes
| Attribute | Type | Description |
|---|---|---|
id | string | Settlement identifier |
status | string | Task status, below |
item_ids | string[] | Selected item identifiers |
amount | string | Total selected amount in currency units |
currency | string | usdc or usdt |
chain | integer | EIP-155 network ID |
recipient_address | string | Destination wallet |
next_action | object / null | Wallet transaction, only in requires_action; otherwise null |
transaction_hash | string / null | Matching collection transaction recognized by the platform; null before recognition |
last_execution_error | object / null | Latest confirmed error; null when absent |
created_at | string | Creation time |
updated_at | string | Last update time |
settled_at | string / null | Time collection finalized; null until complete |
Status and interaction
| Status | Meaning | Merchant action |
|---|---|---|
preparing | Backend prepares the transaction; items reserved | Poll the task |
requires_action | Transaction ready, awaiting wallet execution or chain recognition | Execute returned transaction; then poll |
processing | Matching collection transaction observed; waiting for finality | Poll without resending |
succeeded | Collection finalized | Complete |
failed | Preparation failed before an executable transaction was delivered; items released | Refresh items before creating another task |
Normal flow: preparing → requires_action → processing → succeeded. Preparation failure: preparing → failed.
Wallet signature rejection does not change task status. After sending, status may remain requires_action until recognition; it does not establish that no transaction was sent. Retain wallet submission results and avoid duplicates.
Timeouts, a transaction temporarily not found or rollback before finality are not preparation failures and do not release items. Once processing, the task stays processing during reconciliation. Only after the platform confirms that merchant execution is needed does it return to requires_action with an updated transaction. Only finalized collection reaches succeeded.
Immediately before execution, retrieve the original task and use its current next_action. The platform can update transaction material while preserving item selection, amount, network, stablecoin and destination. requires_action and processing retain reservations. Abandoning the flow does not release items; continue the original Settlement.
next_action
| Attribute | Type | Description |
|---|---|---|
type | string | Always send_transaction |
chain_id | integer | Wallet network; equals Settlement.chain |
transaction.from | string | Required execution wallet |
transaction.to | string | Transaction destination |
transaction.data | string | Hexadecimal calldata with 0x prefix |
transaction.value | string | Native coin base units as hexadecimal, such as 0x0 |
Prompt the wallet to switch to chain_id and execute from the specified from. Do not alter to, data or value. The wallet estimates gas parameters. The merchant wallet signs and sends; the platform does not send on the merchant's behalf.
last_execution_error
| Attribute | Type | Description |
|---|---|---|
code | string | Currently transaction_preparation_failed |
message | string | Human-readable explanation; not for programmatic matching |
This reports confirmed preparation failure only. It does not imply the platform can identify wallet rejection, broadcast failures or every on-chain execution failure.
Settlement example
Addresses and calldata illustrate format only. Execute the complete transaction returned by the API.
{
"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
}
Create a settlement
POST /v1/settlements
Submit item IDs. The platform determines amount, network, stablecoin and destination; do not supply them.
Select 1–100 distinct available items that can be collected to the same wallet in one transaction. Same network, stablecoin and wallet are necessary but do not guarantee every combination is compatible. settlement_items_incompatible requires reducing or changing the selection.
If any item is missing, unavailable or incompatible, the entire request is rejected without creating a task or reserving any items. Successful creation immediately marks all selected items in_progress.
| Attribute | Location | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | Yes | Unique operation key; retain for retries |
item_ids | body | string[] | Yes | 1–100 distinct item identifiers |
After a timeout or unknown creation outcome, retry the original key and parameters. Valid replay returns the first creation result with the same task ID. Retrieve the task for current state.
Request:
POST /v1/settlements
Authorization: Bearer inv_test_...
Content-Type: application/json
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
{
"item_ids": ["si_example"]
}
Response: 200 OK, complete Settlement in preparing:
{
"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
}
Retrieve a settlement
GET /v1/settlements/{id}
| Attribute | Location | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Settlement identifier |
No Idempotency-Key or body is required. Missing or inaccessible tasks return 404.
Request:
GET /v1/settlements/st_example
Authorization: Bearer inv_test_...
Response: 200 OK, complete Settlement in the example format. In requires_action, invoke the wallet using this response's next_action.
List settlements
GET /v1/settlements
List the current merchant's Settlements, ordered by descending creation time then descending ID. Default is all statuses; multiple filters apply together.
| Attribute | Location | Type | Required | Description |
|---|---|---|---|---|
status | query | string | No | preparing, requires_action, processing, succeeded or failed |
chain | query | integer | No | Filter by network ID |
currency | query | string | No | usdc or usdt |
page_size | query | integer | No | Default 20; range 1–100 |
page_token | query | string | No | Prior next_page_token; omit on first page |
No Idempotency-Key or body is required. Preserve filters when paginating.
Request:
GET /v1/settlements?status=succeeded&page_size=20
Authorization: Bearer inv_test_...
Response: 200 OK, complete Settlement objects in data:
{
"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": ""
}
No matches returns {"data":[],"next_page_token":""}.
Business error codes
| HTTP status | Code | Meaning |
|---|---|---|
| 404 | settlement_not_found | Missing or inaccessible Settlement |
| 404 | settlement_item_not_found | Missing or inaccessible selected item |
| 409 | settlement_item_unavailable | Item already reserved or collected; refresh the list and reselect |
| 400 | settlement_items_incompatible | Items cannot be collected in one transaction; change selection |
An empty array, duplicate IDs, too many items or invalid filter values returns a 400 parameter error. Preparation failure occurs after successful creation and is reported through task status and last_execution_error; it does not change the first creation request's successful result.