> ## Documentation Index
> Fetch the complete documentation index at: https://rain-sandbox-trial.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Authorization Reversals

> Simulate reversing an open authorization, either fully (releasing the entire hold) or partially (reducing the authorized amount).

<Warning>
  **Beta Feature**

  The Transaction Simulations feature is currently in beta. API endpoints and behavior may change as we continue to refine the product. Simulation endpoints are available in development environments only — production returns `404 Not Found`.
</Warning>

Simulate reversing an open authorization — for example, when a merchant cancels a transaction before settlement or reduces the authorized amount. Reversals release the hold on the cardholder's balance without creating a posted transaction.

Use this to test how your integration handles authorization reversals, including partial reversals where only a portion of the original hold is released.

## Full vs. partial reversal

* **Full reversal** — Omit `newAmount` to release the entire hold. The transaction amount becomes 0.
* **Partial reversal** — Provide `newAmount` to specify the remaining authorized amount. The difference is released back to the cardholder's available balance.

## Endpoint

```
POST /v1/simulate/transactions/:transactionId/reverse
```

## Path parameters

| Parameter       | Type          | Required | Description                                              |
| --------------- | ------------- | -------- | -------------------------------------------------------- |
| `transactionId` | string (UUID) | Yes      | The ID of an existing authorized transaction to reverse. |

## Headers

| Header         | Type               | Required | Description                                                      |
| -------------- | ------------------ | -------- | ---------------------------------------------------------------- |
| `Api-Key`      | string             | Yes      | Your tenant API key. The tenant scope is resolved from this key. |
| `Content-Type` | `application/json` | Yes      | —                                                                |

## Body

| Field       | Type    | Required | Description                                                                                                            |
| ----------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| `newAmount` | integer | No       | The remaining authorized amount in cents after the reversal. Omit for a full reversal. Must be a non-negative integer. |

```json title="Full reversal (release entire hold)" theme={null}
{}
```

```json title="Partial reversal (reduce authorized amount to $4.00)" theme={null}
{
  "newAmount": 400
}
```

## Response

A successful response returns the transaction ID and status.

```json title="200 OK" theme={null}
{
  "transactionId": "f3a1c92e-1b3d-4d1e-bb22-12c0a4d5b8f9",
  "status": "authorized"
}
```

| Field           | Type          | Description                           |
| --------------- | ------------- | ------------------------------------- |
| `transactionId` | string (UUID) | The transaction ID.                   |
| `status`        | string        | The transaction status: `authorized`. |

## Errors

| Status                      | When                                                                                                                                                                          |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`           | Invalid body (negative `newAmount`), transaction is already settled, transaction is already closed, no card associated with the transaction, or the card has no processor ID. |
| `404 Not Found`             | Endpoint not available in production, simulations are not enabled for your tenant, or the transaction does not exist.                                                         |
| `500 Internal Server Error` | Unhandled error during simulation.                                                                                                                                            |

## Behavior notes

* **Transaction must be an open authorization.** You can only reverse authorizations that have not yet settled or closed.
* **Reversals release holds, not funds.** Unlike refunds, reversals do not move posted funds — they release authorization holds.
* **Triggers webhooks.** The reversal fires the same webhooks as a real authorization reversal.

## Example

```bash title="Full reversal" theme={null}
curl -X POST https://api-dev.rain.xyz/v1/simulate/transactions/f3a1c92e-1b3d-4d1e-bb22-12c0a4d5b8f9/reverse \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

```bash title="Partial reversal" theme={null}
curl -X POST https://api-dev.rain.xyz/v1/simulate/transactions/f3a1c92e-1b3d-4d1e-bb22-12c0a4d5b8f9/reverse \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "newAmount": 400
  }'
```