> ## Documentation Index
> Fetch the complete documentation index at: /llms.txt
> Use this file to discover all available pages before exploring further.

# Refunds

> How to refund a customer, fully or partially, from the dashboard or through the Simiz API.

You can refund a customer from the Simiz dashboard or through the API. A refund is always
attached to an original transaction and goes back to the same payment method the customer
used (Mobile Money or other).

## Refund from the dashboard

1. Open the relevant transaction in the **Transactions** section.
2. Click **Refund**.
3. Choose the amount (full or partial) and the reason, then confirm.

The refund then appears in the **Refunds** section of the dashboard with its current status.

## Refund through the API

```bash
POST /v1/projects/{projectId}/refunds
```

```json
{
  "transactionId": "9c3f2c1e-0d5b-4a7e-9f3a-2b6d8e4c1a90",
  "amount": 2500,
  "reason": "CUSTOMER_REQUEST",
  "reasonDetails": "Order cancelled by the customer"
}
```

| Field           | Required | Description                                              |
| --------------- | -------- | -------------------------------------------------------- |
| `transactionId` | Yes      | Identifier of the original transaction                   |
| `amount`        | Yes      | Amount to refund, in the smallest currency unit          |
| `reason`        | Yes      | `CUSTOMER_REQUEST`, `DUPLICATE`, `FRAUDULENT` or `OTHER` |
| `reasonDetails` | No       | Free-form detail about the reason                        |

To inspect refunds: `GET /v1/projects/{projectId}/refunds` (filterable list) and
`GET /v1/projects/{projectId}/refunds/{id}` (detail).

## Requirements

* Only a transaction with status `COMPLETED` can be refunded.
* Your organization must have enough available balance to cover the amount.

## Partial refunds

Yes, partial refunds are supported. The requested amount must be lower than or equal to the
**remaining refundable amount** (original amount minus refunds already issued). You can
chain several partial refunds on the same transaction, up to the original amount.

## How long a Mobile Money refund takes

How long does a refund take? A refund goes through the following statuses:

| Status       | Meaning                                |
| ------------ | -------------------------------------- |
| `PENDING`    | Created, waiting to be processed       |
| `PROCESSING` | Being executed by the operator         |
| `COMPLETED`  | Funds returned to the customer         |
| `FAILED`     | Failed — the amount remains refundable |

A Mobile Money refund is executed by the **same operator** (licensed partner) as the
original payment: how long the customer waits to be re-credited depends on that Mobile
Money operator and the corridor involved. Simiz does not guarantee a fixed delay — track
the refund status in the dashboard or through the API to know its actual state.

<Note>
  Simiz is a non-custodial orchestrator: refunded funds move through the partner operator,
  never through Simiz.
</Note>