Operations on Stripe Payout objects.

A Payout represents money moving from your Stripe balance to a connected bank account or debit card. Payouts are the outbound leg of money movement — inbound money arrives via Charge / PaymentIntent, and you (or Stripe's automatic schedule) trigger a Payout to settle the balance to a bank.

Key behaviors

• Full CRUDL: create/3, retrieve/3, update/4, list/3, stream!/3.
• cancel/4 and reverse/4 both use the canonical (client, id, params \\ %{}, opts \\ []) shape per D-03. Both endpoints accept at least expand, and reverse additionally accepts metadata.
• The trace_id field decodes into a typed %LatticeStripe.Payout.TraceId{} — pattern-match on payout.trace_id.status to branch your reconciliation flow.
• Unknown future fields from Stripe land in :extra (F-001).
• require_param! validates the payout id pre-network on retrieve, update, cancel, and reverse.

Expandable references

The following fields are typed as binary() | map() | nil because Stripe returns an ID string by default and only inlines the expanded object when you pass expand: [...]:

• destination — expand then cast via LatticeStripe.BankAccount.cast/1 or LatticeStripe.Card.cast/1 as appropriate.
• balance_transaction and failure_balance_transaction — expand then cast via LatticeStripe.BalanceTransaction.from_map/1.

Per D-05, these references stay polymorphic — the guide documents the "expand then cast via expected module" idiom.

Usage

client = LatticeStripe.Client.new!(api_key: "sk_live_...", finch: MyApp.Finch)

# Trigger a manual payout to the default external account
{:ok, payout} = LatticeStripe.Payout.create(client, %{
  "amount" => 5000,
  "currency" => "usd"
})

# Retrieve and branch on trace_id availability
{:ok, payout} = LatticeStripe.Payout.retrieve(client, "po_...")

case payout.trace_id do
  %LatticeStripe.Payout.TraceId{status: "supported", value: trace} ->
    reconcile(trace)

  %LatticeStripe.Payout.TraceId{status: "pending"} ->
    # Stripe will populate trace_id asynchronously — listen for payout.updated
    :wait_for_webhook

  _ ->
    :skip
end

# Cancel a pending payout (no params needed)
{:ok, _} = LatticeStripe.Payout.cancel(client, "po_...")

# Cancel with expand for reconciliation
{:ok, payout} =
  LatticeStripe.Payout.cancel(client, "po_...", %{
    "expand" => ["balance_transaction"]
  })

# Reverse a completed payout with reconciliation metadata
{:ok, reversed} =
  LatticeStripe.Payout.reverse(client, "po_...", %{
    "metadata" => %{"reason" => "customer_dispute"},
    "expand" => ["balance_transaction"]
  })

Idempotency

create, cancel, and reverse are money-moving operations. Client.request/2 auto-generates an idempotency key for mutating requests and reuses it across retries. Pass idempotency_key: in opts to set your own stable key.

Stripe API Reference

• Payouts
• Cancel a payout
• Reverse a payout