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

> Match settled value to your payables, and hold a settlement that is recorded but not yet confirmed.

Reconcile each payable against the payment's frozen `merchantNetAmountAtomic`, keyed on `paymentId`, and prove it with a confirmed transfer. Keying a payment to your own record and surviving duplicate or out-of-order events belong to the payment; see [Reconciliation](/payments/reconciliation).

## The expected total is the frozen net, not the gross

Fees are calculated from the verified destination amount and deducted at final settlement, so the amount the payer sent never matches. Three things move the expected total:

* **A confirmed refund reduces what remains to settle.** The remainder still settles.
* **Fee movement is its own leg** and is not part of the net.
* **Network costs sit outside the calculation** and never appear in the frozen fee fields.

Sum the settlement legs for a payment rather than expecting one row.

## Underpayment does not settle

There is no partial credit path. A payment funded below its obligation does not settle at the lower figure, so there is no settlement row to reconcile and nothing to credit. Receipts accumulate against the obligation until the full amount is verified.

Duplicate, late, overpaid and underpaid receipts are reported in `incidentRecoverySummary`, deliberately separate from `refundSummary`. Keep them separate in your books too, so returning a duplicate never makes a fulfilled payable look refunded.

## Hold a settlement that is recorded but not confirmed

This state looks finished from one angle and unfinished from another, and it produces the most reconciliation bugs.

| What you see | What it means |
| - | - |
| `settlement.txHash` is `null` on the transaction | Broadcast, not confirmed |
| Payment `stage` is `settlement_broadcast` or `settlement_confirming` | Delivery is in progress |
| Payment `status` is still `accepted` | Funds were verified as received. The destination has not been credited |
| `operationalReasonCode` is `settlement_unconfirmed` | It was submitted and confirmation has not arrived |

<Steps>
  <Step title="Hold it open">
    An amount without a confirmed transfer is a pending obligation in your books, not a receipt. Do not release against it.
  </Step>

  <Step title="Create nothing">
    No replacement payment, no second settlement. The first may still confirm.
  </Step>

  <Step title="Read the payment">
    `GET /v2/payments/{paymentId}` is the current answer. Check `status` and `operationalState` separately.
  </Step>

  <Step title="Escalate if it stays">
    A settlement in `requires_intervention` is cleared by a person. See [Settlement failures](/settlement/error-handling).
  </Step>
</Steps>

A payment can sit at `accepted` for a long time while settlement retries, and can stay there permanently if settlement stops for review. `accepted` is not a settled payable.

## Book a returned settlement as its own entry

`payment.settlement_returned` fires when a settlement that was already broadcast is returned or rejected, and the payment's `stage` reads `settlement_returned`. This is an accounting correction, not a change to the financial result: a `succeeded` payment does not become `failed`, and there is no automatic replacement. Hold any credit.

The same applies to `reversed` rows and to `deposit.reversed`. Compensating entries are written, the underlying funds have usually already moved, and nothing is coming back on chain.

## Never reconcile against account activity totals

The account activity totals are a reporting projection, reported as `recorded_activity_projection` and `not_a_custody_balance`. They can be negative, and they do not fall when value settles out to a wallet the customer controls. [Transactions](/payments/transactions) covers what they are for.

## Re-read anything non-terminal past your settlement window

Read anything non-terminal that is older than your expected settlement window, rather than waiting for a delivery that may not arrive. Stop once the payment is terminal: a financial result does not regress, and only the operational axis can still move.

<Card title="Next: Settlement failures" icon="triangle-exclamation" href="/settlement/error-handling">
  Which failures you fix in code, and which a person resolves.
</Card>


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