# Transfer Reversals

## Transfer Reversals

The Transfer Reversal object represents an attempt to pull back funds from a merchant’s payout account after a transfer has been completed. It is created when a refund is initiated for a specific Transfer and records the details of that reversal event.

{% hint style="info" %}
If using `CUSTOM` or `EXTERNAL` transfer settings, the Transfer Reversal object will not be created. In these cases, negative distributions are created during refund processing, and amounts are settled the next time a Transfer is manually initiated.
{% endhint %}

You can retrieve or search for Transfer Reversal objects using the following APIs:

* [Get Transfer Reversal by ID](/api-reference/payments/transfer-reversals/get-transfer-reversal-by-id.md)
* [Get Transfer Reversals by Transfer ID](/api-reference/payments/transfer-reversals/get-transfer-reversals-by-transfer-id.md)
* [Get Transfer Reversals by Payment Provider Transfer ID](/api-reference/payments/transfer-reversals/get-transfer-reversals-by-payment-provider-transfer-id.md)
* [Search Transfer Reversals](/api-reference/payments/transfer-reversals/search-transfer-reversals.md)

## Understanding the Transfer Reversal object

### Sample `TransferReversal`

```json
{
  "id": 335500,
  "object": "transfer_reversal",
  "transfer": 335500,
  "amount": 11428,
  "currency": "USD",
  "status": "PENDING",
  "paypro_data": {
    "paypro_transfer_reversal_id": "trr_3RBesbK29KDiBVld0zLcELFW"
  },
  "date_created": "2025-04-08T16:21:52+0000",
  "date_last_modified": "2025-04-15T16:57:27+0000",
  "errors": []
}
```

The following data is available in a `TransferReversal` object:

| **Field**            | **Type**             | **Sample Value**                                                    | **Description**                                                               |
| -------------------- | -------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `id`                 | Long                 | 335500                                                              | Unique identifier for the transfer reversal.                                  |
| `object`             | String               | "transfer\_reversal"                                                | Name of the object that this represents. Always `transfer_reversal`.          |
| `transfer`           | Long                 | 335500                                                              | Unique identifier for the transfer object that was reversed.                  |
| `amount`             | Long                 | 11428                                                               | Amount, in fractional currency unit (e.g. cents), that was reversed.          |
| `currency`           | String               | "USD"                                                               | Currency of the transfer reversal.                                            |
| `status`             | Enum                 | "PENDING"                                                           | Status of the transfer: one of `PENDING`, `COMPLETE`, or `FAILED`.            |
| `paypro_data`        | Map (string → value) | `{ "paypro_transfer_reversal_id": "trr_3RBesbK29KDiBVld0zLcELFW" }` | Additional metadata from the payment provider.                                |
| `errors`             | List of objects      | `[]`                                                                | Any errors that occurred during reversal. Only populated if there are issues. |
| `date_created`       | String (ISO-8601)    | "2025-04-08T16:21:52+0000"                                          | Timestamp when this object was created.                                       |
| `date_last_modified` | String (ISO-8601)    | "2025-04-15T16:57:27+0000"                                          | Timestamp of the most recent update to the object.                            |

## Webhooks

In addition to the `Transfer` related events, the following events are available for you to subscribe to in order to receive notifications about Transfer Reversals:

* `TRANSFER_REVERSED`
* `TRANSFER_REVERSAL_FAILED`
* `TRANSFER_PARTIALLY_REVERSED`

Learn more [here](broken://pages/fsFQfMpAtlTosYuy698s#transfer-events)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.violet.io/prism/payments/payments-during-checkout/transfer-reversals.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.