Settlement record

LiveUpdated September 13, 2026

Finance, Agents and Sellers. Written for the finance team that signs the policy and the weekly report, people who build agents and the hosts they run in and merchants that receive agent orders.

A settlement record is a record and a reconciliation input, not settlement itself: the money still moves on the buyer’s rail and the merchant’s PSP. Its most important field is finality_class, because a card payment, an ACH debit and an on-chain transfer are three different legal states and no other object names them.

Fields

How it moves

1. Authorized. Created when the rail authorizes: amounts.authorized, rail_refs.authorization_id, expected_settlement_at, finality_class from the adapter.
2. Captured and settled. On Stripe Issuing an issuing_transaction.created of type capture moves the record to captured and, since Issuing posts once, to settled with settled_at and finality_at = settled_at + 120 days. The sandbox rail captures when the merchant confirms fulfillment, or two minutes after authorization.
3. Paid out. When a merchant adapter reports the payout batch (planned with the PSP adapters).
4. Reversed. A completed reversal with fund_change: true updates amounts.reversed and the stage.

The linked record (kind: settlement_record, chain: settlement_of, the last rail object in artifacts.rail_event, strength.subject: third_party_signed) is sealed when the stage reaches settled, paid_out or reversed. SETTLEMENT_OVERDUE and FINALITY_MISMATCH are computed by reconciliation, not stored here.

Fulfillment

The merchant confirms fulfillment three ways: the order webhook order_shipped (or a shipped event in fulfillment.events[]), POST /v0/sellers/fulfillments with { domain, order_id, fulfilled_at, evidence[] }, or the store’s own “Ship” action. Confirmation writes fulfillment on the request and the settlement, sets the payment record’s outcome.status to fulfilled when the record is still open, and on sandbox keys triggers the capture.

GET /v0/settlements/rec_01M25129GZMJXTNQ47TMZRDGHN

{
  "id": "stl_01M2513A9C2K7Q4W8T1N6B3RXH",
  "record_id": "rec_01M25129GZMJXTNQ47TMZRDGHN", "mandate_id": "mnd_01M2512M8FQ7ZK4T1V9W3N6BXC",
  "rail": "stripe_issuing", "stage": "settled",
  "amounts": { "authorized": "24.98", "incremented": "0.00", "captured": "24.98", "reversed": "9.99", "settled": "24.98", "fees": "0.00", "net": "14.99" },
  "finality_class": "reversible", "finality_at": "2027-01-08T17:42:30Z",
  "rail_refs": { "authorization_id": "iauth_1S7Kq2…", "clearing_id": "ipi_1S7Kq9…" },
  "expected_settlement_at": "2026-09-12T17:42:30Z", "settled_at": "2026-09-10T17:42:30Z",
  "fulfillment": { "confirmed_at": "2026-09-11T09:15:00Z", "order_id": "ord_01M2512SM3V3A9R4EBJM8RRRV5", "source": "webhook", "evidence": [{ "type": "tracking", "ref": "1Z…" }] },
  "events": ["enruta:settlement:authorized", "enruta:settlement:captured", "enruta:settlement:settled"],
  "settlement_record_id": "rec_01M2GC2H8W4T7Q1K9N3B6D2H5XR"
}

Three rails, three finalities

Under one policy, three payments could settle on three rails: $24.98 on Stripe Issuing, reversible, final 120 days after settlement; $0.05 over x402 exact, irreversible, final when the block confirms, so a reversal can only be a credit; $8,300 over ACH, conditionally_reversible, final 60 days after settlement. The weekly report shows the three classes side by side so a controller sees at a glance what can still be recovered. Today the first is live; the other two wait for their adapters (x402 2027, ACH with Bill.com from January 2027, read-only first).

Interfaces