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

# Refunds

> Create full or partial refunds via the API, and track them to completion.

Refunds in Float are **asynchronous refund requests**: you submit one via the API, Float reviews and processes it against the shopper's instalment plan, and the request moves through a small state machine until it completes.

## Creating a refund

```bash theme={null}
curl -X POST https://uat-secure.float.co.za/api/refunds \
  -H "Authorization: Bearer $FLOAT_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -H "X-Signature: $SIGNATURE" \
  -d '{
    "checkout_id": "9b2f61c4-6c1e-4b7a-9a1d-3f2a8c0de111",
    "amount": 100000
  }'
```

* `checkout_id` — the `data.id` returned when you [created the checkout](/api-reference/create-checkout).
* `amount` — cents to refund. Anything from 1 cent up to the remaining refundable amount; **partial refunds are supported**, and you can issue multiple partial refunds until the original amount is exhausted.

Response:

```json theme={null}
{
  "data": {
    "id": "5d1a7c9e-2222-4444-8888-aa11bb22cc33",
    "type": "refund_requests",
    "attributes": {
      "amount": 100000,
      "currency": "ZAR",
      "status": "requested",
      "created_at": "2026-07-17T11:00:00Z"
    }
  }
}
```

Store the refund request `id` and track it with [`GET /api/refunds/:id`](/api-reference/get-refund).

## Refund lifecycle

| Status      | Meaning                                                           |
| ----------- | ----------------------------------------------------------------- |
| `requested` | Received by Float, awaiting review/approval.                      |
| `pending`   | Approved and submitted for processing against the shopper's plan. |
| `complete`  | Processed — the shopper's plan has been adjusted/credited.        |
| `failed`    | Processing failed. Contact Float support before retrying.         |

Refunds are not instant: approval and processing can take up to a business day. Reflect `requested`/`pending` as "refund in progress" in your admin UI rather than assuming completion.

## Constraints

<Warning>
  * **100-day window** — the purchase date is day 0; day 100 can still be refunded, day 101 cannot. Later attempts return `422` with `"Orders can only be refunded within 100 days of the purchase date."`
  * **Same-day refunds** — if your integration has **automatic refund approval** enabled, refunds can't be requested on the day of purchase (the ledger entry must settle first): `422` with `"Order can't be refunded on the day of purchase."` Resubmit after 10:00 (your local time) the next day. Integrations with manual review can submit immediately — the request just waits in review.
</Warning>

Additional rules:

* The checkout must be `successful`.
* The sum of all refunds for a checkout can't exceed the original amount (`422` if it would).
* Refunds are processed toward the shopper's instalment plan — remaining instalments are reduced or already-collected amounts returned. You don't need to care which; Float handles the split.

## Cancelling vs refunding

There is no separate "void" or "cancel payment" API. If a shopper cancels **before paying**, the checkout simply ends `cancelled` and no money moves. Once a checkout is `successful`, use a refund.

## Common errors

| HTTP  | Cause                                     | What to do                                                                                             |
| ----- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `422` | Outside the refund window                 | Same-day (auto-refund integrations): retry after 10:00 tomorrow. Over 100 days: contact Float support. |
| `422` | Amount exceeds refundable remainder       | Check prior refunds with [`GET /api/refunds`](/api-reference/list-refunds).                            |
| `404` | Unknown `checkout_id`                     | Verify you stored the checkout `id` (not your own order ID).                                           |
| `400` | Signature mismatch                        | See [request signing](/authentication#request-signing).                                                |
| `429` | Rate limited (1 request/second on create) | Back off and retry.                                                                                    |