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

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

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

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``, and optional ``ach_return_code`` (max 8). 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.

Transition an attempt in_transit -> settled (IS reports the vendor settled the funds). No extra body beyond the common envelope.

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