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

# Settlement

> Simulate settling an open authorization to test merchant fund capture 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 settling an open authorization — for example, when a merchant captures funds after the customer has left. This converts the authorization hold into a posted transaction.

Use this to test how your integration handles the transition from authorization to settlement, including the `transaction.spend.completed` webhook.

## Endpoint

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

## Path parameters

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

## 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 settlement amount in cents (merchant currency). If omitted, settles for the original authorization amount. |

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

## Response

A successful response returns the transaction ID and settled status.

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

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

## Errors

| Status                      | When                                                                                                                                     |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`           | 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` | Invalid currency or unhandled error during simulation.                                                                                   |

## Behavior notes

* **Transaction must be an open authorization.** You can only settle authorizations that have not yet settled or closed.
* **FX conversion applies.** The settlement amount is converted using the transaction's original merchant and billing currencies.
* **Triggers webhooks.** The settlement fires the same webhooks as a real settlement, including `transaction.spend.completed`.

## Example

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