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

# API overview

> Base URLs, conventions, errors, rate limits, and pagination for the Float Merchant API.

The Float Merchant API is a JSON REST API. The current version is **v2** (all paths under `/api`).

## Base URLs

| Environment   | Base URL                             |
| ------------- | ------------------------------------ |
| Sandbox (UAT) | `https://uat-secure.choosefloat.com` |
| Production    | `https://secure.choosefloat.com`     |

## Authentication

Every request needs `Authorization: Bearer <client_secret>`. Mutating requests should also carry an HMAC-SHA512 `X-Signature`. Full details: [Authentication](/authentication).

## Conventions

* **Amounts** are integers in **pence** (`249900` = £2,499.00).
* **Currency** is an ISO 4217 code matching your merchant territory: `GBP`.
* **IDs** are UUIDs.
* **Timestamps** are ISO 8601 UTC.
* Responses follow a JSON:API-flavoured envelope: a `data` object (or array) with `id`, `type`, and `attributes`.

## Endpoints

| Method | Path                                                                 | Purpose                                             |
| ------ | -------------------------------------------------------------------- | --------------------------------------------------- |
| `GET`  | [/api/config](/api-reference/get-config)                             | Your merchant configuration and instalment terms    |
| `GET`  | [/api/merchants/:merchant\_id/config](/api-reference/intermediaries) | Config for a managed merchant (intermediaries only) |
| `POST` | [/api/checkouts](/api-reference/create-checkout)                     | Create a checkout and get a hosted `payment_url`    |
| `GET`  | [/api/checkouts/:id](/api-reference/get-checkout)                    | Fetch one checkout                                  |
| `GET`  | [/api/checkouts](/api-reference/list-checkouts)                      | List your checkouts (paginated)                     |
| `POST` | [/api/refunds](/api-reference/create-refund)                         | Request a full or partial refund                    |
| `GET`  | [/api/refunds/:id](/api-reference/get-refund)                        | Fetch one refund request                            |
| `GET`  | [/api/refunds](/api-reference/list-refunds)                          | List your refund requests (paginated)               |

## Errors

Errors return an `errors` array:

```json theme={null}
{
  "errors": [
    {
      "status": "422",
      "code": "unprocessable_entity",
      "title": "Unprocessable Entity",
      "detail": "Validation failed: Amount has to be between £100.00 and £1,000,000.00"
    }
  ]
}
```

| HTTP | `code`                  | Meaning                                                                                                     |
| ---- | ----------------------- | ----------------------------------------------------------------------------------------------------------- |
| 400  | `bad_request`           | Malformed request or `X-Signature` mismatch                                                                 |
| 401  | `unauthorized`          | Missing or invalid Bearer token                                                                             |
| 404  | `not_found`             | Resource doesn't exist or isn't yours                                                                       |
| 422  | `unprocessable_entity`  | Validation failure — `detail` says what                                                                     |
| 429  | —                       | Rate limited: `{ "error": "Rate limit exceeded. Try again in N seconds" }` where `N` is the throttle window |
| 500  | `internal_server_error` | Something broke on Float's side — safe to retry with backoff                                                |

## Rate limits

| Endpoint                 | Limit                             |
| ------------------------ | --------------------------------- |
| `GET /api/config`        | 5 / hour — **cache the response** |
| `POST /api/checkouts`    | 1 / second                        |
| `GET /api/checkouts`     | 1 / minute                        |
| `GET /api/checkouts/:id` | 5 / minute                        |
| `POST /api/refunds`      | 1 / second                        |
| `GET /api/refunds`       | 1 / minute                        |
| `GET /api/refunds/:id`   | 5 / minute                        |

Exceeding a limit returns `429` with a retry hint. Design around the limits: cache config, prefer callbacks over polling, and keep `GET /api/checkouts/:id` for targeted reconciliation rather than bulk polling.

## Pagination

List endpoints use `page[number]` and `page[items]` query parameters (defaults: `1` and `10`) and return JSON:API `links`:

```json theme={null}
{
  "data": [ ... ],
  "links": {
    "first": ".../api/checkouts?page[number]=1&page[items]=10",
    "last":  ".../api/checkouts?page[number]=5&page[items]=10",
    "prev":  null,
    "next":  ".../api/checkouts?page[number]=2&page[items]=10"
  }
}
```

## OpenAPI specification

A machine-readable OpenAPI 3.1 spec is published per environment at `/docs/api/v2` (e.g. `https://secure.choosefloat.com/api-docs`). It's regenerated on every deployment, so it always matches the running API.