Collect IPP receipts and reconcile funds
Merchant interfaces cover item listing and task retrieval, while creation execution remains pending confirmation. Before using this flow, confirm your account and target environment support both task creation and wallet execution. See API availability.
A Settlement collects received IPP funds in full to the wallet fixed by the original receipt. The merchant wallet signs and sends; the platform prepares transaction material and automatically recognizes results. This is self-custodial collection, not a bank payout or an arbitrary destination transfer.
Only finalized IPP receipts appear as SettlementItems. Direct ERC-20 transfers are excluded. A received payment, an available collection item and finalized collection are distinct facts; reconcile business fulfillment separately from funds management.
Prepare server-side values
The API Key stays on the merchant server. Replace examples with your test Key, the returned Settlement ID and actual available item ID. Persist a separate key for each new task and reuse it for retries. Before starting, confirm your test environment supports the required operations.
export API_BASE='https://connect-dev.invisipay.fi'
export API_KEY='inv_test_REPLACE_WITH_YOUR_SERVER_KEY'
export SETTLEMENT_ID='st_REPLACE_WITH_CREATED_SETTLEMENT_ID'
export SETTLEMENT_CREATE_KEY='a4a0df47-d4d5-4e6b-9fd4-d296f8866cf1'
1. List and select items
curl --fail-with-body --silent --show-error --get \
"$API_BASE/v1/settlement-items" \
-H "Authorization: Bearer $API_KEY" \
--data-urlencode 'status=available' \
--data-urlencode 'chain=8453' \
--data-urlencode 'currency=usdc' \
--data-urlencode 'page_size=20'
The default status filter is available. Filter by network, currency and status. Continue using next_page_token without changing filters. Example item without its pagination envelope:
{
"id": "si_example",
"status": "available",
"amount": "12.5",
"currency": "usdc",
"chain": 8453,
"recipient_address": "0x1234567890abcdef1234567890abcdef12345678",
"settlement_id": null,
"settled_at": null
}
Select 1–100 distinct available items. Same network, currency and recipient_address are necessary, but some combinations still cannot form one transaction. settlement_items_incompatible requires a smaller or different selection. An invalid item rejects the entire batch without creating a task or reserving other items.
Item amounts are decimal strings in currency units. Collection is full amount: do not submit a custom amount, calculate with floating point or round. Settlement.amount sums the selected items. API amount "12.5" is not a calldata integer amount. The original IPP receipt determines recipient_address; creation does not accept another wallet.
2. Create and store the task
curl --fail-with-body --silent --show-error \
"$API_BASE/v1/settlements" \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-H "Idempotency-Key: $SETTLEMENT_CREATE_KEY" \
--data '{"item_ids":["si_REPLACE_WITH_AVAILABLE_ITEM_ID"]}'
HTTP 200 returns a complete preparing Settlement. Save its ID, item_ids and local funds association; the selected items immediately become in_progress. Item selection, amount, network, currency and destination become immutable. There is no cancellation endpoint.
After timeout or crash, retry the original key and item_ids. Valid replay returns the initial creation result with the same task ID. GET provides current state. After the 24-hour idempotency window, establish the original task's outcome before considering another operation. Query or broadcast timeouts do not justify a replacement task.
3. Read the current wallet action
curl --fail-with-body --silent --show-error \
"$API_BASE/v1/settlements/$SETTLEMENT_ID" \
-H "Authorization: Bearer $API_KEY"
Poll while preparing. In requires_action, your server delivers the current next_action to an authenticated merchant frontend, which invokes the wallet. This is a complete example task; addresses and calldata demonstrate format and must not be executed:
{
"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
}
GET the original task immediately before signing. Transaction material may change, but the selected items, amount, network, currency and destination remain fixed. Switch the wallet to next_action.chain_id and use the account in transaction.from. Forward to, data and value unchanged; the wallet estimates gas parameters. value is a hexadecimal native-coin base-unit amount, separate from the decimal currency amount.
The merchant wallet signs and sends; the platform does neither on its behalf. Retain the returned transaction hash with the original task ID. The platform recognizes the matching transaction automatically, without a merchant transaction-hash confirmation endpoint.
4. Wait for finality and recover
| status | Action |
|---|---|
| preparing | Poll; selected items are reserved |
| requires_action | Use current next_action; if already sent, reconcile the original before resending |
| processing | Matching transaction observed; wait for finalized confirmation without resending or creating a new task |
| succeeded | Collection finalized and items settled; record transaction_hash and settled_at |
| failed | Preparation failed before executable material was delivered; items released, so refresh before a new task |
Rejected signing does not change status. A sent transaction not yet observed can leave requires_action. Timeouts, missing lookup results and rollback before finality are not preparation failures and do not release items. processing persists while outcomes are reconciled. Prepare another execution only when the platform explicitly returns requires_action with updated transaction material.
Currently last_execution_error reports transaction_preparation_failed only; it does not establish detection of every wallet, broadcast or chain failure. Abandoned requires_action/processing tasks do not release reservations automatically. Continue the original task instead of waiting for automatic cancellation.
5. Reconcile completed collections
curl --fail-with-body --silent --show-error --get \
"$API_BASE/v1/settlements" \
-H "Authorization: Bearer $API_KEY" \
--data-urlencode 'status=succeeded' \
--data-urlencode 'page_size=20'
Associate task ID and item_ids with the original receipts, amount, network, currency and destination. Record completion using succeeded and settled_at. Empty data means no matches; an empty next_page_token ends pagination. Failed preparation tasks retain historical item_ids, but released items clear settlement_id; that historical association does not establish completion.
For settlement_item_unavailable, refresh inventory. For settlement_items_incompatible, adjust the combination. Distinguish rejected HTTP parameters from preparation failure after a task was accepted. See the complete settlement API for fields, pagination, states and errors.