> ## 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.

# Refund

> Simulate refunding a settled transaction to test merchant refund flows.

<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 refunding a settled transaction — for example, when a merchant issues a refund after the original purchase was captured. This creates a credit back to the cardholder.

Use this to test how your integration handles refunds, including the `transaction.spend.completed` webhook with a refund completion reason.

## Endpoint

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

## Path parameters

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

## 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                                                                                     |
| -------- | ------- | -------- | ----------------------------------------------------------------------------------------------- |
| `amount` | integer | No       | The refund amount in cents (merchant currency). If omitted, refunds the full settlement amount. |

```json title="Example request" theme={null}
{
  "amount": 2500
}
```

## Response

A successful response returns the transaction ID and settled status with a refund completion reason.

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

| Field              | Type          | Description                        |
| ------------------ | ------------- | ---------------------------------- |
| `transactionId`    | string (UUID) | The transaction ID.                |
| `status`           | string        | The transaction status: `settled`. |
| `completionReason` | string        | The completion type: `REFUND`.     |

## Errors

| Status                      | When                                                                                                                  |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`           | Transaction is not yet settled, 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` | Invalid currency or unhandled error during simulation.                                                                |

## Behavior notes

* **Transaction must be settled.** You can only refund transactions that have already been settled.
* **FX conversion applies.** The refund amount is converted using the transaction's original merchant and billing currencies.
* **Triggers webhooks.** The refund fires the same webhooks as a real refund, including `transaction.spend.completed` with `completionReason: "REFUND"`.

## Example

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