Settlement transactions

A payment produces several transaction rows; the one with financialLegKind: "settlement" records value reaching the destination. Field definitions, statuses and paging for the full record are on Transactions.

Select the settlement row in your code

curl "https://staging-api-v2.stableyard.fi/v2/accounts/acct_123/transactions?limit=100" \
  -u "$APP_ID:$APP_SECRET"

There is no settlement filter on the list endpoint. Group the rows by paymentId, then select the one whose financialLegKind is settlement. The fee on the same payment is a separate row with financialLegKind: "fee_payout", so gross, fee and net tie out without recomputation. A chain that can fund a payment but cannot hold a settlement destination never produces a settlement row.

Read `settlement.amount` for what was delivered

{
  "id": "txn_123",
  "accountId": "acct_123",
  "status": "completed",
  "financialLegKind": "settlement",
  "paymentId": "payment_123",
  "sourceType": "payment",
  "sourceId": "payment_123",
  "settlement": {
    "amount": {
      "asset": { "symbol": "USDC", "decimals": 6, "chainId": 42161, "kind": "token" },
      "amount": "24875000"
    },
    "txHash": "0xabc123..."
  }
}

Use settlement.amount, not the row’s top-level amount, which is stated from the requested account’s perspective.

settlement.txHash is nullable. A row can exist with the amount recorded and the hash still absent, because the transfer was broadcast and has not confirmed. A null hash means not yet confirmed, not no transfer. Treat it as a pending obligation, never as a receipt.

Tie the row back to the payment

To answer	Read
Which payment settled	`paymentId` on the row
Where it was supposed to go	The payment’s immutable `settlement` snapshot: `destinationAddress`, `chainId`, `assetCode`
What it was supposed to be	`merchantNetAmountAtomic` in the payment’s frozen `fees`
When it completed	`succeededAt` on the payment, or the `createdAt` on the row’s ledger entries
What a counterparty can verify	`settlement.txHash`

The settlement row carries no timestamp field, so the dated answer comes from the payment or from the ledger entries on the detail read.

Deposits report settlement on the deposit

A deposit at a reusable address settles to the same destination and carries its own settlement record, so you can follow confirmation without re-checking the source transaction.

curl https://staging-api-v2.stableyard.fi/v2/accounts/acct_123/deposits \
  -u "$APP_ID:$APP_SECRET"

Field	What it holds
`settlement.status`	`pending`, `settled`, `failed` or `requires_intervention`
`settlement.txHash`	The delivering transfer, `null` until it exists
`settlement.settledAt`	When settlement confirmed
`settlement.reasonCode`	A stable machine-readable reason when it needs review. Raw provider errors are never exposed
`netSettlementAmount`	What the destination receives after fees
`settlementProfileSnapshot`	The destination frozen at the moment the deposit was detected

A deposit detected before a destination change still settles to its settlementProfileSnapshot. Reconcile against the snapshot, not against the account’s current profile.

Next: Settlement reconciliation

Match settled value to your own payables.

Start here

Settling

Operating it

Settlement transactions

Select the settlement row in your code

Read `settlement.amount` for what was delivered

Tie the row back to the payment

Deposits report settlement on the deposit

Next: Settlement reconciliation

​Select the settlement row in your code

​Read settlement.amount for what was delivered

​Tie the row back to the payment

​Deposits report settlement on the deposit

Next: Settlement reconciliation

Select the settlement row in your code

Read `settlement.amount` for what was delivered

Tie the row back to the payment

Deposits report settlement on the deposit