> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stableyard.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Settlement transactions

> Find the settlement row for a payment, read what was delivered, and tie it back to the payment.

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](/payments/transactions).

## Select the settlement row in your code

```bash theme={null}
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

```json theme={null}
{
  "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.

<Warning>
  `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.
</Warning>

## 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.

```bash theme={null}
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.

<Card title="Next: Settlement reconciliation" icon="scale-balanced" href="/settlement/reconciliation">
  Match settled value to your own payables.
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.