Operations on Stripe Transfer Reversal objects — standalone top-level module.
A Transfer Reversal returns some or all of a previously created Transfer from the destination connected account back to the platform balance. See the Stripe Transfer Reversal API.
Design: standalone module, no Transfer.reverse/4 delegator
Phase 18 decision D-02 locks this as a top-level module addressed by
(transfer_id, reversal_id), mirroring /v1/transfers/:transfer/reversals/:id.
LatticeStripe.Transfer deliberately does not expose a reverse/4
delegator — users reach for TransferReversal.create/4 directly. This
mirrors the Phase 17 AccountLink / LoginLink precedent and stripe-java's
own top-level TransferReversal class.
Usage
client = LatticeStripe.Client.new!(api_key: "sk_live_...", finch: MyApp.Finch)
# Create a full reversal (no amount = reverse the entire transfer)
{:ok, reversal} = LatticeStripe.TransferReversal.create(client, "tr_...", %{})
# Create a partial reversal
{:ok, reversal} = LatticeStripe.TransferReversal.create(client, "tr_...", %{
"amount" => 500,
"description" => "Partial reversal — platform issue"
})
# Retrieve
{:ok, reversal} = LatticeStripe.TransferReversal.retrieve(client, "tr_...", "trr_...")
# Update metadata
{:ok, reversal} = LatticeStripe.TransferReversal.update(client, "tr_...", "trr_...", %{
"metadata" => %{"internal_id" => "rev_42"}
})
# List reversals for a transfer
{:ok, resp} = LatticeStripe.TransferReversal.list(client, "tr_...")
# Stream lazily (auto-pagination)
client
|> LatticeStripe.TransferReversal.stream!("tr_...")
|> Enum.to_list()Pre-network param validation
All public functions validate that transfer_id (and reversal_id where
present) are non-empty binaries before any HTTP call. Passing nil or ""
raises ArgumentError immediately, so tests do not need mock setup to
cover the missing-id path.
Stripe API Reference
See the Stripe Transfer Reversal API.
Summary
Functions
Creates a new TransferReversal for the given transfer.
Like create/4 but raises on failure.
Converts a decoded Stripe API map to a %TransferReversal{} struct.
Lists TransferReversals for the given transfer.
Like list/4 but raises on failure.
Retrieves a TransferReversal by transfer id and reversal id.
Like retrieve/4 but raises on failure.
Returns a lazy stream of all TransferReversals for the given transfer (auto-pagination).
Updates a TransferReversal's metadata.
Like update/5 but raises on failure.
Types
@type t() :: %LatticeStripe.TransferReversal{ amount: integer() | nil, balance_transaction: LatticeStripe.BalanceTransaction.t() | String.t() | nil, created: integer() | nil, currency: String.t() | nil, destination_payment_refund: LatticeStripe.Refund.t() | String.t() | nil, extra: map(), id: String.t() | nil, metadata: map() | nil, object: String.t(), source_refund: LatticeStripe.Refund.t() | String.t() | nil, transfer: LatticeStripe.Transfer.t() | String.t() | nil }
A Stripe Transfer Reversal object.
See the Stripe Transfer Reversal API
for field definitions. Unknown fields are preserved in :extra (F-001).
Functions
@spec create(LatticeStripe.Client.t(), String.t(), map(), keyword()) :: {:ok, t()} | {:error, LatticeStripe.Error.t()}
Creates a new TransferReversal for the given transfer.
Sends POST /v1/transfers/:transfer_id/reversals with the given params.
Raises ArgumentError (pre-network) if transfer_id is nil or empty.
Parameters
client- A%LatticeStripe.Client{}structtransfer_id- The Transfer ID ("tr_...") to reverseparams- Optional params:"amount","description","metadata","refund_application_fee","expand"opts- Per-request overrides
@spec create!(LatticeStripe.Client.t(), String.t(), map(), keyword()) :: t()
Like create/4 but raises on failure.
Converts a decoded Stripe API map to a %TransferReversal{} struct.
Maps all known Stripe Transfer Reversal fields explicitly. Any unrecognized
fields are collected into :extra (F-001).
from_map(nil) returns nil.
@spec list(LatticeStripe.Client.t(), String.t(), map(), keyword()) :: {:ok, LatticeStripe.Response.t()} | {:error, LatticeStripe.Error.t()}
Lists TransferReversals for the given transfer.
Sends GET /v1/transfers/:transfer_id/reversals.
Raises ArgumentError (pre-network) if transfer_id is nil or empty.
@spec list!(LatticeStripe.Client.t(), String.t(), map(), keyword()) :: LatticeStripe.Response.t()
Like list/4 but raises on failure.
@spec retrieve(LatticeStripe.Client.t(), String.t(), String.t(), keyword()) :: {:ok, t()} | {:error, LatticeStripe.Error.t()}
Retrieves a TransferReversal by transfer id and reversal id.
Sends GET /v1/transfers/:transfer_id/reversals/:reversal_id.
Raises ArgumentError (pre-network) if either id is nil or empty.
@spec retrieve!(LatticeStripe.Client.t(), String.t(), String.t(), keyword()) :: t()
Like retrieve/4 but raises on failure.
@spec stream!(LatticeStripe.Client.t(), String.t(), map(), keyword()) :: Enumerable.t()
Returns a lazy stream of all TransferReversals for the given transfer (auto-pagination).
Raises ArgumentError (pre-network) if transfer_id is nil or empty.
@spec update(LatticeStripe.Client.t(), String.t(), String.t(), map(), keyword()) :: {:ok, t()} | {:error, LatticeStripe.Error.t()}
Updates a TransferReversal's metadata.
Sends POST /v1/transfers/:transfer_id/reversals/:reversal_id.
Raises ArgumentError (pre-network) if either id is nil or empty.
Like update/5 but raises on failure.