Stripe: Update a reversal

← Transfers operations · Get started

Operation stripe.posttransferstransferreversalsid

Provider route: POST /v1/transfers/{transfer}/reversals/{id}. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/stripe with npm, or alter-sdk-stripe with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { StripeIntegration } from "@alter-ai/stripe";

async function execute(input: Parameters<StripeIntegration["transfers"]["postTransfersTransferReversalsId"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new StripeIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.transfers.postTransfersTransferReversalsId(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_stripe import StripeIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = StripeIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.transfers.post_transfers_transfer_reversals_id(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
path	object	Required within parent	Additional keys: not allowed
path.id	string	Required within parent	Maximum length: 5000
path.transfer	string	Required within parent	Maximum length: 5000
headers	object	Optional	Additional keys: not allowed
headers.Idempotency-Key	string	Optional	Minimum length: 1 Maximum length: 255
body	Model	Optional	Expand Update a payout — request body — body

Referenced models: Update a payout — request body — body

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	Model	Root	Expand Update a reversal — response body

Referenced models: Update a reversal — response body

Schemas

703 more schemas are linked from the tables above, on the schema pages.

Update a reversal — response body

Field	Type	Presence	Description and constraints
$	object	Root	[Stripe Connect](https://docs.stripe.com/connect) platforms can reverse transfers made to a connected account, either entirely or partially, and can also specify whether to refund any related application fees. Transfer reversals add to the platform's balance and subtract from the destination account's balance. Reversing a transfer that was made for a [destination charge](/docs/connect/destination-charges) is allowed only up to the amount of the charge. It is possible to reverse a [transfer_group](https://docs.stripe.com/connect/separate-charges-and-transfers#transfer-options) transfer only if the destination account has enough balance to cover the reversal. Related guide: [Reverse transfers](https://docs.stripe.com/connect/separate-charges-and-transfers#reverse-transfers)
amount	JSON	Required within parent
amount (anyOf 1)	integer	Alternative	Amount, in cents (or local equivalent).
amount (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
balance_transaction	JSON	Optional
balance_transaction (anyOf 1)	JSON	Alternative	Balance transaction that describes the impact on your account balance.
balance_transaction (anyOf 1) (anyOf 1)	string	Alternative	Maximum length: 5000
balance_transaction (anyOf 1) (anyOf 2)	Model	Alternative	Expand Retrieve a balance transaction — balance get Balance History Id — response body
balance_transaction (anyOf 2)	null	Alternative
created	JSON	Required within parent
created (anyOf 1)	integer	Alternative	Time at which the object was created. Measured in seconds since the Unix epoch. Format: unix-time
created (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
currency	string	Required within parent	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies). Format: currency
destination_payment_refund	JSON	Optional
destination_payment_refund (anyOf 1)	JSON	Alternative	Linked payment refund for the transfer reversal.
destination_payment_refund (anyOf 1) (anyOf 1)	string	Alternative	Maximum length: 5000
destination_payment_refund (anyOf 1) (anyOf 2)	Model	Alternative	Expand Cancel a refund — response body
destination_payment_refund (anyOf 2)	null	Alternative
id	string	Required within parent	Unique identifier for the object. Maximum length: 5000
metadata	JSON	Optional
metadata (anyOf 1)	object	Alternative	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Additional keys: see wildcard field
metadata (anyOf 1).*	string	Additional keys	Maximum length: 500
metadata (anyOf 2)	null	Alternative
object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: transfer_reversal
source_refund	JSON	Optional
source_refund (anyOf 1)	JSON	Alternative	ID of the refund responsible for the transfer reversal.
source_refund (anyOf 1) (anyOf 1)	string	Alternative	Maximum length: 5000
source_refund (anyOf 1) (anyOf 2)	Model	Alternative	Expand Cancel a refund — response body
source_refund (anyOf 2)	null	Alternative
transfer	JSON	Required within parent	ID of the transfer that was reversed.
transfer (anyOf 1)	string	Alternative	Maximum length: 5000
transfer (anyOf 2)	Model	Alternative	Expand Create a transfer — response body

Referenced models: Retrieve a balance transaction — balance get Balance History Id — response body, Cancel a refund — response body, Create a transfer — response body

Update a payout — request body — body

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
expand	array	Optional	Specifies which fields in the response should be expanded.
expand[]	string	Each item	Maximum length: 5000
metadata	JSON	Optional	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`.
metadata (anyOf 1)	object	Alternative	Additional keys: see wildcard field
metadata (anyOf 1).*	string	Additional keys
metadata (anyOf 2)	string	Alternative	One of:

Retrieve a balance transaction — balance.getBalanceHistoryId — response body — source / This transaction relates to the Stripe object / object: connect collection transfer

Field	Type	Presence	Description and constraints
$	object	Root
amount	JSON	Required within parent
amount (anyOf 1)	integer	Alternative	Amount transferred, in cents (or local equivalent).
amount (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
currency	string	Required within parent	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies). Format: currency
destination	JSON	Required within parent	ID of the account that funds are being collected for.
destination (anyOf 1)	string	Alternative	Maximum length: 5000
destination (anyOf 2)	Model	Alternative	Expand Create an account — response body
id	string	Required within parent	Unique identifier for the object. Maximum length: 5000
livemode	boolean	Required within parent	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: connect_collection_transfer

Referenced models: Create an account — response body

Retrieve a balance transaction — balance get Balance History Id — response body — fee details item

Field	Type	Presence	Description and constraints
$	object	Root
amount	JSON	Required within parent
amount (anyOf 1)	integer	Alternative	Amount of the fee, in cents.
amount (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
application	JSON	Optional
application (anyOf 1)	string	Alternative	ID of the Connect application that earned the fee. Maximum length: 5000
application (anyOf 2)	null	Alternative
currency	string	Required within parent	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies). Format: currency
description	JSON	Optional
description (anyOf 1)	string	Alternative	An arbitrary string attached to the object. Often useful for displaying to users. Maximum length: 5000
description (anyOf 2)	null	Alternative
type	string	Required within parent	Type of the fee, one of: `application_fee`, `payment_method_passthrough_fee`, `stripe_fee`, `tax`, or `withheld_tax`. Maximum length: 5000

Retrieve a balance transaction — balance.getBalanceHistoryId — response body — source / This transaction relates to the Stripe object / object: reserve transaction

Field	Type	Presence	Description and constraints
$	object	Root
amount	JSON	Required within parent
amount (anyOf 1)	integer	Alternative
amount (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
currency	string	Required within parent	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies). Format: currency
description	JSON	Optional
description (anyOf 1)	string	Alternative	An arbitrary string attached to the object. Often useful for displaying to users. Maximum length: 5000
description (anyOf 2)	null	Alternative
id	string	Required within parent	Unique identifier for the object. Maximum length: 5000
object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: reserve_transaction

Delete a customer — response body

Field	Type	Presence	Description and constraints
$	object	Root
deleted	boolean	Required within parent	Always true for a deleted object Known values: True
id	string	Required within parent	Unique identifier for the object. Maximum length: 5000
object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: customer

Cancel a Setup Intent — response body — managed payments value enabled

Field	Type	Presence	Description and constraints
$	object	Root
enabled	boolean	Required within parent	Set to `true` to enable [Managed Payments](https://docs.stripe.com/payments/managed-payments), Stripe's merchant of record solution, for this session.

Policy, approvals and errors

SDK function policy ID: stripe.posttransferstransferreversalsid. Catalog operation: PostTransfersTransferReversalsId. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Pinned headers: {"Stripe-Version": "2026-09-30.endive"}

Official provider source