settlement.held

A confirmed deposit is waiting in its address: the master wallet cannot pay the fee and network costs yet, or a release guard applies (reason).

cTpeWay sends this event as an HTTP POST to every webhook endpoint subscribed to it. Verify the signature before you trust the body: see Webhooks.

Payload

Field	Type	Description
`id`	string	Unique event id, `evt_…`. Use it to deduplicate deliveries.
`type`	string	Always `settlement.held`.
`api_version`	string	Always `v1`.
`created`	integer	Unix time in seconds.
`livemode`	boolean	`false` for events from the test environment.
`data`	object
`data.object`	object
`data.object.id`	string
`data.object.status`	string	One of `pending`, `held`, `releasing`, `released`, `failed`, `reverted`.
`data.object.payment_id`	string
`data.object.invoice_id` optional	string
`data.object.deposit_address_id` optional	string
`data.object.network`	string
`data.object.asset`	string
`data.object.asset_id`	string
`data.object.native_asset`	string
`data.object.gross`	string	The deposit, base units of `asset`. A whole number written as a string of digits.
`data.object.usd_value`	string	A decimal number written as a string, with up to 8 decimal places.
`data.object.fee_bps`	integer
`data.object.fee_native`	string	Platform fee owed, base units of `native_asset`. A whole number written as a string of digits.
`data.object.fee_source`	string	One of `deposit`, `master`.
`data.object.fee_paid`	string	A whole number written as a string of digits.
`data.object.fee_carried`	string	A whole number written as a string of digits.
`data.object.required_native` optional	string	Native coin the master wallet must hold for this release. A whole number written as a string of digits.
`data.object.master_wallet_address` optional	string
`data.object.reason` optional	string	Why it is held (status `held`) or why it failed (status `failed`); absent in any other status. `insufficient_master_balance`: Held: the master wallet has too little native coin to pay the platform fee and the network costs of the release (token deposits). Released by itself once the wallet is topped up. `uneconomic`: Held: the network fee of the release is estimated at more than half of what the deposit is worth. Looked at again on every planning run and released when the estimate falls. `below_sweep_min`: Held: the deposit is worth less than the merchant’s minimum for a sweep. It stays in its address until that setting allows it or another release from the same address takes it along. `payment_orphaned`: Failed: a chain reorganisation removed the payment while its release was under way. The settlement returns to the queue by itself if the payment confirms again. `funds_missing`: Failed: the deposit is no longer at its address and no release on record moved it. Needs an operator. `not_releasable`: Failed: the network cannot release this deposit as it stands (an asset or address it does not support, or a release plan that did not pass its checks). Needs an operator. `transaction_failed`: Failed: a transaction of the release was rejected or can no longer be included. Retried by an operator; what was already paid is not paid again. `replanning`: Failed for a moment: a transaction prepared for the release could not be used as it was, and the release is being planned again by itself. Nothing to do. `unclassified`: Failed: for a reason outside this list. Needs an operator. One of `insufficient_master_balance`, `uneconomic`, `below_sweep_min`, `payment_orphaned`, `funds_missing`, `not_releasable`, `transaction_failed`, `replanning`, `unclassified`.
`data.object.fee_tx` optional	string
`data.object.topup_tx` optional	string
`data.object.sweep_tx` optional	string
`data.object.network_fees`	string	A whole number written as a string of digits.
`data.object.net_released` optional	string	A whole number written as a string of digits.
`data.object.simulated`	boolean
`data.object.confirmed_at`	string (date-time)
`data.object.held_since` optional	string (date-time)
`data.object.released_at` optional	string (date-time)
`data.object.failed_at` optional	string (date-time)

A field marked optional can be missing from a payload.

Example

{
  "id": "string",
  "type": "settlement.held",
  "api_version": "v1",
  "created": 0,
  "livemode": true,
  "data": {
    "object": {
      "id": "string",
      "status": "held",
      "payment_id": "string",
      "invoice_id": "string",
      "deposit_address_id": "string",
      "network": "string",
      "asset": "string",
      "asset_id": "string",
      "native_asset": "string",
      "gross": "1000000",
      "usd_value": "10.00",
      "fee_bps": 0,
      "fee_native": "1000000",
      "fee_source": "deposit",
      "fee_paid": "1000000",
      "fee_carried": "1000000",
      "required_native": "1000000",
      "master_wallet_address": "string",
      "reason": "insufficient_master_balance",
      "fee_tx": "string",
      "topup_tx": "string",
      "sweep_tx": "string",
      "network_fees": "1000000",
      "net_released": "1000000",
      "simulated": true,
      "confirmed_at": "2026-01-01T00:00:00.000Z",
      "held_since": "2026-01-01T00:00:00.000Z",
      "released_at": "2026-01-01T00:00:00.000Z",
      "failed_at": "2026-01-01T00:00:00.000Z"
    }
  }
}

The values are placeholders generated from the schema. They show the shape, not real data.