disbursements

Operator admin-terminate of a stuck pending ACH attempt (justification required).

Per-state counts + amount sums: {by_state: {<state>: {count, amount}}}.

Code
Optional filters are enum / UUID / date validated against the published
contract instead of being forwarded raw. added_from / added_to mirror the
`list` grid so a date-filtered view gets a matching aggregate card
(BC-22436).

Store the regulatory receipt IS built for an attempt (BC-25447).

Code
The lifecycle callbacks carry the receipt for the outcome they report, so
this endpoint is for a receipt that follows no transition: a corrected
document, or a late one for an attempt that has already reached its final
state and has no transition left to ride on. It renders in the request
rather than on a worker, because here there is no money movement whose
report a render failure could spoil -- the caller is told it failed.

Body adds ``receipt_html`` and ``receipt_title`` -- a finished document and
the name to file it under. The service sanitizes the markup and replaces
whatever receipt the attempt already holds, so a redelivery leaves one
file rather than two. Optional ``captured_for_state`` is the attempt state
the receipt reports; a receipt for a state the attempt has left is dropped,
so a late retry cannot replace a newer receipt. A dropped receipt comes
back with ``data.dropped`` and a ``_warning_`` naming the attempt's state.
A stale receipt is superseded by the one for that state; a receipt sent
ahead of its own transition is one the sender resends once that
transition is accepted. Name the state: a receipt sent without one is
stored as of unknown state, and the nightly receipt audit reports it stale
until a receipt that names its state replaces it. The receipt is logged
as ``<redacted>``: it names the payee, their bank and the amount.

``integration_instance_external_id`` is passed on rather than consumed by
the front gate alone: like the ``mark_*`` transitions, the service binds
the attempt to the calling instance, so one ACH_ISSUANCE instance cannot
attach a receipt to another's payout.

The bank disclosure rendered at the foot of the page: {html: "..."}.

Code
A regulatory statement Stripe requires (BC-25516). It is HTML because the
required phrase carries a link, and it is a setting rather than a literal
because Bruno asked for one that BriteCore can revise without a release.

Read, not written, here: the value is edited in Advanced Settings, where
``settings.god_only`` restricts it to BriteCore staff. That path applies no
sanitizer of its own -- ``saveSettingValue`` stores the raw string -- so
THIS is the only point at which the value is made safe, and it is the
reason the sanitize is on the read.

Deliberately its own endpoint rather than a field on the grid read. The
disclosure has to appear on every tab and must not disappear when the grid
fails to load; a regulatory statement is not a property of a page of rows.

Returns the empty string for an absent, blank or wholly-stripped value --
the page renders nothing at all in that case, so there is no shape here for
"present but empty" to be told apart from "absent".

Operator cancel of an in_transit ACH attempt (justification required).

Reconcile a stuck pending ACH attempt against the vendor: if the vendor holds a reference -> advance to in_transit (writing the ref in the CAS); else stay pending. Idempotent.

Code
This endpoint owns the unit of work around the vendor round-trip (the
service no longer commits/rolls back): validate + capture the row, COMMIT to
close the read txn BEFORE the synchronous get_vendor_reference call (so no DB
transaction is held across the vendor HTTP round-trip), then apply the vendor
result and COMMIT the transition + exported projection. On error the
@api_request wrapper rolls back the request (a lost CAS wrote 0 rows, so
there is nothing to strand).

Send a selection of parked (ready_to_pay) attempts (BC-25734).

Code
Balance-checks the selection total up front, all or nothing, then flips each
row `ready_to_pay` -> `pending`. Nothing is dispatched here: `pending` is
what the minutecron sweeper leases, so dispatch happens exactly where it
always has.

``disbursement_attempt_ids`` are ATTEMPT ids, which is why this is not a
variant of `issue`: every write under `issue` is an INSERT keyed on the
obligation, and `ready_to_pay` sits in the obligation mutex, so `issue`
returns blocked_by_mutex on precisely the rows an operator is trying to
send.

Returns ``{total_released, already_sent_ids, not_sent_ids}``. A refusal -- unknown id, a
row that is no longer ready to pay, a total the funding account cannot
cover, or a Just-in-time (Batch) funded pool, which this flow does not
support yet -- comes back as ``success=false`` with the sentence the dialog
shows, and writes nothing.

Owns its commit boundary the way `check_vendor` does: money is at stake and
the operator's response must not depend on a later request-unload hook.

Full serialized attempt plus folded single-row source enrichment.

Code
Absent row -> success=true, data null/empty; bad UUID -> BCValidationError.

Issue (or re-issue / retry) a batch of Commission Payments via ACH.

Code
``items`` is a list of ``{commission_payment_id, payment_method_id}``. The
re-issue path is the same call: a failed row released the obligation mutex,
so re-issuing INSERTs a new pending attempt and leaves the failed row as
history. Serializes each IssuanceResult: ``{items:[...]}``.

``integration_instance_id`` and every item's ``commission_payment_id`` /
``payment_method_id`` are required UUIDs (validated against the published
contract) so malformed / missing ids fail up front rather than falling
through to per-item service results.

All-attempts grid (lean rows only, no source fan-out).

Code
``transaction_type`` routes to ``list_by_type``; otherwise ``list_all``.
Returns ``{items, page, page_size, total}``.

``exclude_states`` (BC-25734) drops whole states from the result. It is what
the grid's "Hide paid payments" toggle sends, and it composes with ``state``
rather than overriding it -- a caller that both selects and excludes the
same state has asked for nothing and gets nothing.

NOT named ``list``: api/v2 routing maps the last URL segment straight to a
function name, and ``def list`` shadowed the builtin for this whole module,
so a plain ``isinstance(x, list)`` anywhere in here raised TypeError. That
bit BC-24593 in production-shaped traffic. Public URL is therefore
``POST /api/v2/disbursements/list_disbursements``.

Transition an attempt to failed.

Code
Body adds ``failure_origin`` (one of vendor_rejected / recipient_returned /
cancel_acknowledged; ``admin_terminate`` is operator-only and rejected by
the engine as ``incompatible_current_state``), ``failure_code``,
``failure_reason``, optional ``ach_return_code`` (max 8), and the optional
``receipt_html`` / ``receipt_title`` the regulatory receipt is captured
from. The required source state is derived from ``failure_origin`` by the
engine (vendor_rejected<-pending, recipient_returned / cancel_acknowledged
<-in_transit).

Transition an attempt pending -> in_transit (IS reports the vendor accepted the submission). Body adds vendor_reference_id (the IS/vendor handle for the operation, max 255) to the common envelope, plus the optional receipt_html / receipt_title the regulatory receipt is captured from.

Transition an attempt in_transit -> settled (IS reports the vendor settled the funds). Body adds the optional receipt_html / receipt_title the regulatory receipt is captured from.

Latest failed-with-no-live-successor attempts, deduped per obligation.

Code
Returns ``{items, page, page_size, total, count, amount_sum}`` (the grid +
the deduped aggregate card). rail / integration_instance_id / added_from /
added_to mirror the `list` grid so a filtered all-attempts view gets a
matching worklist total (BC-22436); there is no state filter (the surface is
inherently the terminal `failed` set).

All attempts for one obligation, newest first: {items:[...]}.

Code
Both ``transaction_type`` (enum) and ``transaction_id`` (UUID) are required
and validated against the published contract.

Record a disbursement made OUTSIDE BriteCore (rail='manual'), created directly settled. Justification required; operator resolved server-side.

Batched per-attempt source enrichment (payee name, live-successor flag, commission source block).

Code
``disbursement_attempt_ids`` is a REQUIRED, bounded list of UUIDs (validated
by the request schema): a missing/omitted value is a malformed request
(success=false), NOT a silent empty ``{}``, and a bare UUID string is
rejected rather than iterated character-by-character downstream.

Commission obligations that are claimable but have NO disbursement attempt yet, each tagged ready_to_send or awaiting_funds (BC-24980, TXN T5).

Code
The attempt-table reads (``list_disbursements`` and friends) cannot see a
payment that is still waiting to go out; this is the read that can.
Membership is the commission export's own claim classifier, and the tag
is the SAME whole-selection funding-gate verdict the export applies up
front, so the page and the export agree. Returns ``{items, page,
page_size, total, funding_gate: {applied, available, obligation_total,
blocked}}``; ``funding_gate.blocked`` is why every row is
``awaiting_funds``. Fails open like the gate: funding unconfigured or a
failed balance read -> ``applied=false`` and every row ``ready_to_send``.

``transaction_type`` is optional and, in this build, only Commission
Payment (anything else is a validation error, not an empty page).

Write check number, check date, and/or cleared date onto already-exported outbound checks (return premium, claim payment, or commission payment).

Code
Same shape as the export helper in ``api.v2.utils``: validate the batch,
lock matching rows in three IN queries, bulk-update the successes, and
write force-overwrite notes in the same transaction. Request-level errors
(bad UUID, duplicate ids, invalid dates) fail the call. Per-row errors
(not found, not exported, voided, canceled/rejected/transferred return
premium, electronic or net commission, negative commission, claim
recovery or untyped claim) go in ``failed`` and do not roll back the rest.

Parameters
----------
records : list of dict, required
    Batch of partial updates. Each object must include ``id`` (UUID). Any of
    ``check_number``, ``check_date``, ``cleared_date`` may be sent; omitted
    fields are left alone. A mixed batch is allowed. The row must already
    be exported and must not be voided, canceled, rejected, transferred,
    an electronic, net, or negative commission, or a non-payment claim.
    Replacing a value that is already set
    requires ``force_update`` on that record and writes a system note on
    the related policy, claim, or payee contact. ``check_number`` must be
    an integer from 1 to 2147483647. Check dates accept ``YYYY-MM-DD``,
    ``YYYY-MM-DD HH:MM:SS``, or ``YYYY-MM-DDTHH:MM:SS``.

    ::
        {
            "records": [
                {"id": "<uuid>", "check_number": 1001, "check_date": "2026-08-26"},
                {"id": "<uuid>", "cleared_date": "2026-09-15"},
                {"id": "<uuid>", "check_number": 1002, "force_update": true}
            ]
        }

Returns
-------
data : dict
    ``updated`` is the list of rows that were written, including the
    resolved ``payment_type``. ``failed`` is per-row errors (not found,
    not exported, voided, canceled/rejected/transferred return premium,
    electronic, net, or negative commission, claim recovery or untyped
    claim, or a field that is already set without ``force_update``).
    Request-level errors use the standard v2 envelope with ``data: []``.

Schemas: ``lib/api/api_specs/request-update_exported_check_details.json``
and ``lib/api/api_specs/response-update_exported_check_details.json``.