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

# How Float works

> The payment lifecycle, checkout statuses, and what they mean for your order flow.

## The payment flow

```mermaid theme={null}
sequenceDiagram
    participant S as Shopper
    participant M as Your server
    participant F as Float

    M->>F: POST /api/checkouts
    F-->>M: payment_url + checkout id
    M->>S: Redirect to payment_url
    S->>F: Selects instalments, enters card, completes 3-D Secure
    F->>M: POST notify_url (signed callback: successful / cancelled)
    M-->>F: 2xx (optionally { "redirect_url": "..." })
    F->>S: Redirect to redirect_url / success_url / cancel_url
```

Behind the scenes, a successful payment is a **pre-authorisation** of the first instalment on the shopper's existing credit card. Float then collects the remaining instalments monthly. None of that concerns your integration: from your side, the order is paid in full the moment the checkout is `successful`, and Float settles with you per your merchant agreement.

## Checkout statuses

A checkout (`GET /api/checkouts/:id`) is always in exactly one of these states:

| Status            | Meaning                                                | What you should do                                  |
| ----------------- | ------------------------------------------------------ | --------------------------------------------------- |
| `received`        | Checkout created; shopper hasn't completed payment yet | Wait. The shopper may still be on the payment page. |
| `successful`      | Payment authorised — the order is paid                 | **Fulfil the order.**                               |
| `cancelled`       | Shopper cancelled or abandoned the payment             | Release stock, mark the order unpaid.               |
| `invalid_payload` | The checkout request contained invalid data            | Fix the request; create a new checkout.             |

<Note>
  There is **no `failed` status**. A declined card doesn't end the session — the shopper can retry on the payment page until they succeed or cancel. You will only ever be notified of a terminal `successful` or `cancelled` outcome.
</Note>

## When is it safe to fulfil?

Fulfil when **your `notify_url` receives a verified callback with `"status": "successful"`** — or when `GET /api/checkouts/:id` returns `successful`.

Do **not** fulfil based on:

* the shopper landing on your `success_url` (redirects can be forged, or never happen if the browser closes), or
* the checkout merely existing.

If your callback endpoint was down, Float retries for around three hours ([details](/guides/callbacks#delivery-and-retries)); you can always reconcile with `GET /api/checkouts/:id`.

## Payment sessions expire

A shopper has roughly **30 minutes** to complete payment once they land on the payment page. If the session lapses, create a fresh checkout rather than re-sending an old `payment_url`.

## Amounts and currency

* All Merchant API amounts are **integers in cents**: `249900` = R2,499.00.
* Currency is `ZAR`. The checkout currency must match your merchant territory.
* The checkout `amount` must fall inside the range in your [merchant config](/api-reference/get-config) `rules`.

## Instalment terms

Your merchant config `rules` define which terms (number of monthly payments) are available per amount band:

```json theme={null}
{ "from_amount": 10000, "to_amount": 100000000, "terms": [1, 2, 3, 4, 5, 6] }
```

The **shopper** picks the term on Float's payment page; the callback tells you what they chose via `number_of_payments`. Use the config to render messaging like *"From R416.50/month with Float"* on product pages (price ÷ maximum term).

## Refunds at a glance

Refunds are asynchronous: you create a **refund request**, Float reviews and processes it, and its status moves `requested → pending → complete` (or `failed`). Partial refunds are supported; refunds must happen within **100 days** of the purchase date. Full details and edge cases in the [refunds guide](/guides/refunds).