Rename Reversal to TransferReversal

.hark/changes/2026-09-17_zacchua_rename-reversal-transferreversal.change.md

@@ -0,0 +1,7 @@
+---
+title: Rename `stripe.Reversal` to `stripe.TransferReversal`
+pr_url: https://github.com/stripe/stripe-python/pull/1915
+semver_level: major
+---
+
+- ⚠️ Rename the `stripe.Reversal` resource class to `stripe.TransferReversal`. Update references and type annotations to use `stripe.TransferReversal`.

.hark/migration-guides/v16.md

@@ -8,6 +8,24 @@ You will almost certainly need before/after code examples and information about
 See: https://github.com/stripe/hark#writing-a-great-migration-guide
 -->
 
+## Rename `stripe.Reversal` to `stripe.TransferReversal`
+
+The class representing a transfer reversal has been renamed from `stripe.Reversal` to `stripe.TransferReversal`.
+
+This change affects integrations that reference `stripe.Reversal` directly, including imports, class comparisons, `isinstance` checks, and type annotations. Replace those references with `stripe.TransferReversal`:
+
+```python
+# Before
+reversal = stripe.Transfer.retrieve_reversal("tr_123", "trr_123")
+isinstance(reversal, stripe.Reversal)
+
+# After
+reversal = stripe.Transfer.retrieve_reversal("tr_123", "trr_123")
+isinstance(reversal, stripe.TransferReversal)
+```
+
+The methods for creating, retrieving, modifying, and listing transfer reversals have not changed. Code that only calls those methods and reads attributes from the returned object does not require an update.
+
 ## `StripeObject.request()` has been removed
 
 The deprecated `StripeObject.request()` method has been removed. If you used it to make custom API requests, create a `StripeClient` and use `raw_request()` instead:

stripe/__init__.py

@@ -447,7 +447,7 @@ def set_app_info(
     from stripe._reserve_transaction import (
         ReserveTransaction as ReserveTransaction,
     )
-    from stripe._reversal import Reversal as Reversal
+    from stripe._transfer_reversal import TransferReversal as TransferReversal
     from stripe._review import Review as Review
     from stripe._review_service import ReviewService as ReviewService
     from stripe._search_result_object import (
@@ -835,7 +835,7 @@ def set_app_info(
     "RequestOptions": ("stripe._request_options", False),
     "RequestorOptions": ("stripe._requestor_options", False),
     "ReserveTransaction": ("stripe._reserve_transaction", False),
-    "Reversal": ("stripe._reversal", False),
+    "TransferReversal": ("stripe._transfer_reversal", False),
     "Review": ("stripe._review", False),
     "ReviewService": ("stripe._review_service", False),
     "SearchResultObject": ("stripe._search_result_object", False),

stripe/_balance_transaction.py

@@ -19,7 +19,7 @@
     from stripe._payout import Payout
     from stripe._refund import Refund
     from stripe._reserve_transaction import ReserveTransaction
-    from stripe._reversal import Reversal
+    from stripe._transfer_reversal import TransferReversal
     from stripe._tax_deducted_at_source import TaxDeductedAtSource
     from stripe._topup import Topup
     from stripe._transfer import Transfer
@@ -146,7 +146,7 @@ class FeeDetail(StripeObject):
                 "TaxDeductedAtSource",
                 "Topup",
                 "Transfer",
-                "Reversal",
+                "TransferReversal",
             ]
         ]
     ]

stripe/_object_classes.py

@@ -226,7 +226,7 @@
         "stripe._reserve_transaction",
         "ReserveTransaction",
     ),
-    "transfer_reversal": ("stripe._reversal", "Reversal"),
+    "transfer_reversal": ("stripe._transfer_reversal", "TransferReversal"),
     "review": ("stripe._review", "Review"),
     "setup_attempt": ("stripe._setup_attempt", "SetupAttempt"),
     "setup_intent": ("stripe._setup_intent", "SetupIntent"),

stripe/_refund.py

@@ -17,7 +17,7 @@
     from stripe._customer import Customer
     from stripe._payment_intent import PaymentIntent
     from stripe._payment_method import PaymentMethod
-    from stripe._reversal import Reversal
+    from stripe._transfer_reversal import TransferReversal
     from stripe.params._refund_cancel_params import RefundCancelParams
     from stripe.params._refund_create_params import RefundCreateParams
     from stripe.params._refund_expire_params import RefundExpireParams
@@ -473,15 +473,15 @@ class PresentmentDetails(StripeObject):
     """
     This is the transaction number that appears on email receipts sent for this refund.
     """
-    source_transfer_reversal: Optional[ExpandableField["Reversal"]]
+    source_transfer_reversal: Optional[ExpandableField["TransferReversal"]]
     """
     The transfer reversal that's associated with the refund. Only present if the charge came from another Stripe account.
     """
     status: Optional[str]
     """
     Status of the refund. This can be `pending`, `requires_action`, `succeeded`, `failed`, or `canceled`. Learn more about [failed refunds](https://docs.stripe.com/refunds#failed-refunds).
     """
-    transfer_reversal: Optional[ExpandableField["Reversal"]]
+    transfer_reversal: Optional[ExpandableField["TransferReversal"]]
     """
     This refers to the transfer reversal object if the accompanying transfer reverses. This is only applicable if the charge was created using the destination parameter.
     """

stripe/_transfer.py

@@ -15,7 +15,7 @@
     from stripe._account import Account
     from stripe._balance_transaction import BalanceTransaction
     from stripe._charge import Charge
-    from stripe._reversal import Reversal
+    from stripe._transfer_reversal import TransferReversal
     from stripe.params._transfer_create_params import TransferCreateParams
     from stripe.params._transfer_create_reversal_params import (
         TransferCreateReversalParams,
@@ -102,7 +102,7 @@ class Transfer(
     """
     String representing the object's type. Objects of the same type share the same value.
     """
-    reversals: ListObject["Reversal"]
+    reversals: ListObject["TransferReversal"]
     """
     A list of reversals that have been applied to the transfer.
     """
@@ -256,12 +256,12 @@ async def retrieve_async(
     @classmethod
     def list_reversals(
         cls, id: str, /, **params: Unpack["TransferListReversalsParams"]
-    ) -> ListObject["Reversal"]:
+    ) -> ListObject["TransferReversal"]:
         """
         You can see a list of the reversals belonging to a specific transfer. Note that the 10 most recent reversals are always available by default on the transfer object. If you need more than those 10, you can use this API method and the limit and starting_after parameters to page through additional reversals.
         """
         return cast(
-            ListObject["Reversal"],
+            ListObject["TransferReversal"],
             cls._static_request(
                 "get",
                 "/v1/transfers/{id}/reversals".format(id=sanitize_id(id)),
@@ -272,12 +272,12 @@ def list_reversals(
     @classmethod
     async def list_reversals_async(
         cls, id: str, /, **params: Unpack["TransferListReversalsParams"]
-    ) -> ListObject["Reversal"]:
+    ) -> ListObject["TransferReversal"]:
         """
         You can see a list of the reversals belonging to a specific transfer. Note that the 10 most recent reversals are always available by default on the transfer object. If you need more than those 10, you can use this API method and the limit and starting_after parameters to page through additional reversals.
         """
         return cast(
-            ListObject["Reversal"],
+            ListObject["TransferReversal"],
             await cls._static_request_async(
                 "get",
                 "/v1/transfers/{id}/reversals".format(id=sanitize_id(id)),
@@ -288,7 +288,7 @@ async def list_reversals_async(
     @classmethod
     def create_reversal(
         cls, id: str, /, **params: Unpack["TransferCreateReversalParams"]
-    ) -> "Reversal":
+    ) -> "TransferReversal":
         """
         When you create a new reversal, you must specify a transfer to create it on.
 
@@ -297,7 +297,7 @@ def create_reversal(
         Once entirely reversed, a transfer can't be reversed again. This method will return an error when called on an already-reversed transfer, or when trying to reverse more money than is left on a transfer.
         """
         return cast(
-            "Reversal",
+            "TransferReversal",
             cls._static_request(
                 "post",
                 "/v1/transfers/{id}/reversals".format(id=sanitize_id(id)),
@@ -308,7 +308,7 @@ def create_reversal(
     @classmethod
     async def create_reversal_async(
         cls, id: str, /, **params: Unpack["TransferCreateReversalParams"]
-    ) -> "Reversal":
+    ) -> "TransferReversal":
         """
         When you create a new reversal, you must specify a transfer to create it on.
 
@@ -317,7 +317,7 @@ async def create_reversal_async(
         Once entirely reversed, a transfer can't be reversed again. This method will return an error when called on an already-reversed transfer, or when trying to reverse more money than is left on a transfer.
         """
         return cast(
-            "Reversal",
+            "TransferReversal",
             await cls._static_request_async(
                 "post",
                 "/v1/transfers/{id}/reversals".format(id=sanitize_id(id)),
@@ -332,12 +332,12 @@ def retrieve_reversal(
         id: str,
         /,
         **params: Unpack["TransferRetrieveReversalParams"],
-    ) -> "Reversal":
+    ) -> "TransferReversal":
         """
         By default, you can see the 10 most recent reversals stored directly on the transfer object, but you can also retrieve details about a specific reversal stored on the transfer.
         """
         return cast(
-            "Reversal",
+            "TransferReversal",
             cls._static_request(
                 "get",
                 "/v1/transfers/{transfer}/reversals/{id}".format(
@@ -354,12 +354,12 @@ async def retrieve_reversal_async(
         id: str,
         /,
         **params: Unpack["TransferRetrieveReversalParams"],
-    ) -> "Reversal":
+    ) -> "TransferReversal":
         """
         By default, you can see the 10 most recent reversals stored directly on the transfer object, but you can also retrieve details about a specific reversal stored on the transfer.
         """
         return cast(
-            "Reversal",
+            "TransferReversal",
             await cls._static_request_async(
                 "get",
                 "/v1/transfers/{transfer}/reversals/{id}".format(
@@ -376,14 +376,14 @@ def modify_reversal(
         id: str,
         /,
         **params: Unpack["TransferModifyReversalParams"],
-    ) -> "Reversal":
+    ) -> "TransferReversal":
         """
         Updates the specified reversal by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
 
         This request only accepts metadata and description as arguments.
         """
         return cast(
-            "Reversal",
+            "TransferReversal",
             cls._static_request(
                 "post",
                 "/v1/transfers/{transfer}/reversals/{id}".format(
@@ -400,14 +400,14 @@ async def modify_reversal_async(
         id: str,
         /,
         **params: Unpack["TransferModifyReversalParams"],
-    ) -> "Reversal":
+    ) -> "TransferReversal":
         """
         Updates the specified reversal by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
 
         This request only accepts metadata and description as arguments.
         """
         return cast(
-            "Reversal",
+            "TransferReversal",
             await cls._static_request_async(
                 "post",
                 "/v1/transfers/{transfer}/reversals/{id}".format(

stripe/_reversal.py → stripe/_transfer_reversal.py

@@ -13,7 +13,7 @@
     from stripe._refund import Refund
 
 
-class Reversal(UpdateableAPIResource["Reversal"]):
+class TransferReversal(UpdateableAPIResource["TransferReversal"]):
     """
     [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