@pwngh/economy-lab
    Preparing search index...

    Variable settlePayoutConst

    settlePayout: (
        fields: FieldsOf<K>,
    ) => {
        actor: Principal;
        idempotencyKey: string;
        kind: "settlePayout";
        providerAmount?: Amount;
        providerRef: string;
        sagaId: string;
    } = ...

    Builds a settlePayout operation: the SUBMITTED to SETTLED step of the payout saga, driven by the rail's verified "payout settled" webhook — the rail has already paid, and this records it. It posts two balanced entries in one transaction: the reserve empties from PAYOUT_RESERVE into REVENUE, and the gross USD leaves trust (USD_CLEARING against TRUST_CASH). The posted figures come from the saga's reserve at its locked payout rate; providerAmount is recorded for reconciliation but never posted. Restricted to a system or operator actor — an end user must never settle their own payout. No rejected path: a missing saga faults OP.MALFORMED, a not-yet-submitted or already-FAILED saga faults SAGA.INVALID_TRANSITION (retryably for the race with the submit sweep). The settlement applies at most once: a redelivered webhook replays as duplicate by its event-derived idempotencyKey, and a fresh key against an already-SETTLED saga answers duplicate too.

    Type Declaration

      • (
            fields: FieldsOf<K>,
        ): {
            actor: Principal;
            idempotencyKey: string;
            kind: "settlePayout";
            providerAmount?: Amount;
            providerRef: string;
            sagaId: string;
        }

      • Parameters

        • fields: FieldsOf<K>

        Returns {
            actor: Principal;
            idempotencyKey: string;
            kind: "settlePayout";
            providerAmount?: Amount;
            providerRef: string;
            sagaId: string;
        }

        • actor: Principal
        • idempotencyKey: string
        • kind: "settlePayout"
        • OptionalproviderAmount?: Amount

          The USD amount the provider reported settling. Recorded for audit/reconciliation only: the figures actually posted are the rate-derived ones settlePayout computes (gross USD from the reserve at the payout rate, less the rail fee), so the provider's report never sets the posted amount. Absent when the rail's callback carries no figure (Tilia's does not); the reconcile feed still checks amounts against the rail's settlement report.

        • providerRef: string

          The provider's settlement reference for this payout (the rail's own id for the disbursement), recorded for the audit trail. Carried from the inbound provider webhook that drives the settle.

        • sagaId: string
    const outcome = await economy.submit(settlePayout({
      idempotencyKey: idempotencyKey('whk', 'evt_ps_8821'),
      actor: systemActor('webhook:tilia'),
      sagaId: 'pay_9f2c',
      providerRef: 'acct_77/ps_8821',
    }));

    Settings
    Member Visibility