Skip to main content

Settlement items and settlements API

Check API availability and confirm access in your target environment before integrating.

OperationMethod and routeAvailability
List settlement itemsGET /v1/settlement-itemsMerchant route confirmed
Create a settlementPOST /v1/settlementsExecution support pending
Retrieve a settlementGET /v1/settlements/{id}Merchant route confirmed
List settlementsGET /v1/settlementsMerchant route confirmed
Execution support pending

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​

AttributeTypeDescription
idstringSettlement item identifier used when creating a Settlement
statusstringavailable, in_progress or settled
amountstringFull collection amount in currency units
currencystringStablecoin: usdc or usdt
chainintegerEIP-155 network ID
recipient_addressstringDestination wallet fixed by the original IPP receipt; immutable
settlement_idstring / nullCurrently associated task; null if unassociated
settled_atstring / nullTime collection reached finalized confirmation; null until complete
StatusMeaning
availableReceipt finalized, uncollected and unreserved
in_progressReserved by a collection task that has not completed
settledCollection 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.

AttributeLocationTypeRequiredDescription
statusquerystringNoavailable, in_progress or settled; default available
chainqueryintegerNoFilter by network ID
currencyquerystringNousdc or usdt
page_sizequeryintegerNoDefault 20; range 1–100
page_tokenquerystringNoPrior 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&currency=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​

AttributeTypeDescription
idstringSettlement identifier
statusstringTask status, below
item_idsstring[]Selected item identifiers
amountstringTotal selected amount in currency units
currencystringusdc or usdt
chainintegerEIP-155 network ID
recipient_addressstringDestination wallet
next_actionobject / nullWallet transaction, only in requires_action; otherwise null
transaction_hashstring / nullMatching collection transaction recognized by the platform; null before recognition
last_execution_errorobject / nullLatest confirmed error; null when absent
created_atstringCreation time
updated_atstringLast update time
settled_atstring / nullTime collection finalized; null until complete

Status and interaction​

StatusMeaningMerchant action
preparingBackend prepares the transaction; items reservedPoll the task
requires_actionTransaction ready, awaiting wallet execution or chain recognitionExecute returned transaction; then poll
processingMatching collection transaction observed; waiting for finalityPoll without resending
succeededCollection finalizedComplete
failedPreparation failed before an executable transaction was delivered; items releasedRefresh 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​

AttributeTypeDescription
typestringAlways send_transaction
chain_idintegerWallet network; equals Settlement.chain
transaction.fromstringRequired execution wallet
transaction.tostringTransaction destination
transaction.datastringHexadecimal calldata with 0x prefix
transaction.valuestringNative 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​

AttributeTypeDescription
codestringCurrently transaction_preparation_failed
messagestringHuman-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.

AttributeLocationTypeRequiredDescription
Idempotency-KeyheaderstringYesUnique operation key; retain for retries
item_idsbodystring[]Yes1–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}
AttributeLocationTypeRequiredDescription
idpathstringYesSettlement 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.

AttributeLocationTypeRequiredDescription
statusquerystringNopreparing, requires_action, processing, succeeded or failed
chainqueryintegerNoFilter by network ID
currencyquerystringNousdc or usdt
page_sizequeryintegerNoDefault 20; range 1–100
page_tokenquerystringNoPrior 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 statusCodeMeaning
404settlement_not_foundMissing or inaccessible Settlement
404settlement_item_not_foundMissing or inaccessible selected item
409settlement_item_unavailableItem already reserved or collected; refresh the list and reselect
400settlement_items_incompatibleItems 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.

Settlement workflow · Common conventions