Operations on Stripe Refund objects.
A Refund represents a return of a charge to a customer's payment method. You can create a refund for a PaymentIntent or Charge.
Key behaviors
- The
payment_intentparameter is required when creating a refund — anArgumentErroris raised immediately (pre-network) if it is missing. - Refunds cannot be deleted. Use
cancel/4to cancel a pending refund. - Updates are limited to the
metadatafield only (Stripe API constraint).
Usage
client = LatticeStripe.Client.new!(api_key: "sk_live_...", finch: MyApp.Finch)
# Create a full refund for a PaymentIntent
{:ok, refund} = LatticeStripe.Refund.create(client, %{
"payment_intent" => "pi_...",
"reason" => "requested_by_customer"
})
# Create a partial refund
{:ok, refund} = LatticeStripe.Refund.create(client, %{
"payment_intent" => "pi_...",
"amount" => 500
})
# Retrieve a refund
{:ok, refund} = LatticeStripe.Refund.retrieve(client, "re_...")
# Update a refund's metadata
{:ok, refund} = LatticeStripe.Refund.update(client, "re_...", %{
"metadata" => %{"order_id" => "ord_123"}
})
# Cancel a pending refund
{:ok, refund} = LatticeStripe.Refund.cancel(client, "re_...")
# List refunds with optional filters
{:ok, resp} = LatticeStripe.Refund.list(client, %{"payment_intent" => "pi_..."})
refunds = resp.data.data # [%Refund{}, ...]
# Stream all refunds lazily (auto-pagination)
client
|> LatticeStripe.Refund.stream!()
|> Stream.take(100)
|> Enum.each(&process_refund/1)Security and Inspect
The Inspect implementation shows only id, object, amount, currency, and status.
Payment intent IDs, charge IDs, and other operational details are hidden.
Stripe API Reference
See the Stripe Refund API for the full object reference and available parameters.
Summary
Functions
Cancels a pending Refund.
Like cancel/4 but raises LatticeStripe.Error on failure.
Creates a new Refund for a PaymentIntent.
Like create/3 but raises LatticeStripe.Error on failure.
Also raises ArgumentError when payment_intent param is missing.
Converts a decoded Stripe API map to a %Refund{} struct.
Lists Refunds with optional filters.
Like list/3 but raises LatticeStripe.Error on failure.
Retrieves a Refund by ID.
Like retrieve/3 but raises LatticeStripe.Error on failure.
Returns a lazy stream of all Refunds matching the given params (auto-pagination).
Updates a Refund by ID.
Like update/4 but raises LatticeStripe.Error on failure.
Types
@type t() :: %LatticeStripe.Refund{ amount: integer() | nil, balance_transaction: String.t() | nil, charge: String.t() | nil, created: integer() | nil, currency: String.t() | nil, destination_details: map() | nil, extra: map(), failure_balance_transaction: String.t() | nil, failure_reason: String.t() | nil, id: String.t() | nil, instructions_email: String.t() | nil, metadata: map() | nil, next_action: map() | nil, object: String.t(), payment_intent: String.t() | nil, reason: String.t() | nil, receipt_number: String.t() | nil, source_transfer_reversal: String.t() | nil, status: String.t() | nil, transfer_reversal: String.t() | nil }
A Stripe Refund object.
See the Stripe Refund API for field definitions.
Functions
@spec cancel(LatticeStripe.Client.t(), String.t(), map(), keyword()) :: {:ok, t()} | {:error, LatticeStripe.Error.t()}
Cancels a pending Refund.
Sends POST /v1/refunds/:id/cancel and returns {:ok, %Refund{status: "canceled"}}.
Only refunds with status: "pending" can be canceled.
Parameters
client- A%LatticeStripe.Client{}structid- The Refund ID stringparams- Optional cancel params (typically empty%{})opts- Per-request overrides
Returns
{:ok, %Refund{status: "canceled"}}on success{:error, %LatticeStripe.Error{}}on failure
Example
{:ok, refund} = LatticeStripe.Refund.cancel(client, "re_...")@spec cancel!(LatticeStripe.Client.t(), String.t(), map(), keyword()) :: t()
Like cancel/4 but raises LatticeStripe.Error on failure.
@spec create(LatticeStripe.Client.t(), map(), keyword()) :: {:ok, t()} | {:error, LatticeStripe.Error.t()}
Creates a new Refund for a PaymentIntent.
Sends POST /v1/refunds with the given params and returns {:ok, %Refund{}}.
The payment_intent param is required — an ArgumentError is raised immediately
(before any network call) if it is missing.
Parameters
client- A%LatticeStripe.Client{}structparams- Map of Refund attributes. Required:"payment_intent". Optional:"amount"(omit for full refund),"reason","metadata".opts- Per-request overrides (e.g.,[idempotency_key: "..."])
Returns
{:ok, %Refund{}}on success{:error, %LatticeStripe.Error{}}on failure
Example
{:ok, refund} = LatticeStripe.Refund.create(client, %{
"payment_intent" => "pi_3N...",
"reason" => "requested_by_customer"
})@spec create!(LatticeStripe.Client.t(), map(), keyword()) :: t()
Like create/3 but raises LatticeStripe.Error on failure.
Also raises ArgumentError when payment_intent param is missing.
Converts a decoded Stripe API map to a %Refund{} struct.
Maps all known Stripe Refund fields. Any unrecognized fields are
collected into the extra map so no data is silently lost.
Example
refund = LatticeStripe.Refund.from_map(%{
"id" => "re_...",
"amount" => 2000,
"currency" => "usd",
"status" => "succeeded"
})@spec list(LatticeStripe.Client.t(), map(), keyword()) :: {:ok, LatticeStripe.Response.t()} | {:error, LatticeStripe.Error.t()}
Lists Refunds with optional filters.
Sends GET /v1/refunds and returns {:ok, %Response{data: %List{}}} with
typed %Refund{} items. All params are optional.
Parameters
client- A%LatticeStripe.Client{}structparams- Filter params (e.g.,%{"payment_intent" => "pi_...", "limit" => "20"})opts- Per-request overrides
Returns
{:ok, %Response{data: %List{data: [%Refund{}, ...]}}}on success{:error, %LatticeStripe.Error{}}on failure
Example
{:ok, resp} = LatticeStripe.Refund.list(client, %{"payment_intent" => "pi_..."})
Enum.each(resp.data.data, &IO.inspect/1)@spec list!(LatticeStripe.Client.t(), map(), keyword()) :: LatticeStripe.Response.t()
Like list/3 but raises LatticeStripe.Error on failure.
@spec retrieve(LatticeStripe.Client.t(), String.t(), keyword()) :: {:ok, t()} | {:error, LatticeStripe.Error.t()}
Retrieves a Refund by ID.
Sends GET /v1/refunds/:id and returns {:ok, %Refund{}}.
Parameters
client- A%LatticeStripe.Client{}structid- The Refund ID string (e.g.,"re_...")opts- Per-request overrides
Returns
{:ok, %Refund{}}on success{:error, %LatticeStripe.Error{}}on failure
@spec retrieve!(LatticeStripe.Client.t(), String.t(), keyword()) :: t()
Like retrieve/3 but raises LatticeStripe.Error on failure.
@spec stream!(LatticeStripe.Client.t(), map(), keyword()) :: Enumerable.t()
Returns a lazy stream of all Refunds matching the given params (auto-pagination).
Emits individual %Refund{} structs, fetching additional pages as needed.
Raises LatticeStripe.Error if any page fetch fails.
Parameters
client- A%LatticeStripe.Client{}structparams- Filter params (e.g.,%{"payment_intent" => "pi_...", "limit" => "100"})opts- Per-request overrides
Returns
An Enumerable.t() of %Refund{} structs.
Example
client
|> LatticeStripe.Refund.stream!()
|> Stream.take(500)
|> Enum.to_list()@spec update(LatticeStripe.Client.t(), String.t(), map(), keyword()) :: {:ok, t()} | {:error, LatticeStripe.Error.t()}
Updates a Refund by ID.
Sends POST /v1/refunds/:id with the given params and returns {:ok, %Refund{}}.
Note: the Stripe API only supports updating the metadata field on a Refund.
Parameters
client- A%LatticeStripe.Client{}structid- The Refund ID stringparams- Map of fields to update (only"metadata"is accepted by Stripe)opts- Per-request overrides
Returns
{:ok, %Refund{}}on success{:error, %LatticeStripe.Error{}}on failure
@spec update!(LatticeStripe.Client.t(), String.t(), map(), keyword()) :: t()
Like update/4 but raises LatticeStripe.Error on failure.