Settlement reconciliation

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.

​

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