Type Alias Operation

Type Declaration

• {
      actor: Principal;
      amount: Amount;
      idempotencyKey: string;
      kind: "topUp";
      source: string;
      userId: string;
  }
• {
      actor: Principal;
      ageRestricted?: boolean;
      buyerId: string;
      giftTo?: string;
      idempotencyKey: string;
      kind: "spend";
      orderId: string;
      price: Amount;
      recipients: Recipient[];
      sku: string;
  }

  • actor: Principal

  • OptionalageRestricted?: boolean

  • buyerId: string

  • OptionalgiftTo?: string

    A gift: the buyer pays and is screened as usual, but the SKU is granted to this user id, with no wallet-to-wallet credit or ownership transfer. Omitted (or equal to buyerId) for a self-purchase.

  • idempotencyKey: string

  • kind: "spend"

  • orderId: string

  • price: Amount

  • recipients: Recipient[]

  • sku: string

• {
      actor: Principal;
      idempotencyKey: string;
      kind: "refund";
      orderId: string;
      reason?: string;
  }
• {
      actor: Principal;
      amount: Amount;
      idempotencyKey: string;
      key?: string;
      kind: "clawback";
      orderId?: string;
      reason?: string;
      userId: string;
  }
• {
      actor: Principal;
      amount: Amount;
      idempotencyKey: string;
      kind: "requestPayout";
      userId: string;
  }

  • actor: Principal

  • amount: Amount

    amount is the seller's earned credits. It is set aside in the payout-reserve account and ultimately paid out to them as real USD.

  • idempotencyKey: string

  • kind: "requestPayout"

  • userId: string

• {
      actor: Principal;
      idempotencyKey: string;
      kind: "subscribe";
      periodMs: number;
      price: Amount;
      sellerId: string;
      sku: string;
      userId: string;
  }
• {
      actor: Principal;
      idempotencyKey: string;
      kind: "cancelSubscription";
      subscriptionId: string;
  }
• {
      actor: Principal;
      attrs?: EntitlementAttributes;
      idempotencyKey: string;
      kind: "grantEntitlement";
      sku: string;
      userId: string;
  }
• {
      actor: Principal;
      idempotencyKey: string;
      kind: "revokeEntitlement";
      reason?: string;
      sku: string;
      userId: string;
  }
• {
      actor: Principal;
      amount: Amount;
      expiresAt: number;
      idempotencyKey: string;
      kind: "grantPromo";
      userId: string;
  }
• {
      account: AccountRef;
      actor: Principal;
      amount: Amount;
      idempotencyKey: string;
      kind: "adjust";
      reason: string;
  }
• {
      actor: Principal;
      idempotencyKey: string;
      kind: "reverse";
      reason: string;
      txnId: string;
  }
• {
      actor: Principal;
      idempotencyKey: string;
      kind: "reversePayout";
      providerReported?: boolean;
      reason: string;
      sagaId: string;
      userId: string;
  }

  • actor: Principal

  • idempotencyKey: string

  • kind: "reversePayout"

  • OptionalproviderReported?: boolean

    True when the payout rail itself reported the disbursement failed (a verified payoutFailed webhook). It waives the still-live SUBMITTED refusal: the provider has said it will not settle this payout, so returning the reserve promptly cannot double-pay. An operator's manual reverse leaves this unset and stays gated until the payout ages past maxPayoutAgeMs.

  • reason: string

  • sagaId: string

  • userId: string

• {
      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