API overview

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.float.co.za`
Production	`https://secure.float.co.za`

Authentication

Every request needs Authorization: Bearer <client_secret>. Mutating requests should also carry an HMAC-SHA512 X-Signature. Full details: Authentication.

Conventions

Amounts are integers in cents (249900 = R2,499.00).
Currency is an ISO 4217 code matching your merchant territory: ZAR.
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	Your merchant configuration and instalment terms
`GET`	/api/merchants/:merchant_id/config	Config for a managed merchant (intermediaries only)
`POST`	/api/checkouts	Create a checkout and get a hosted `payment_url`
`GET`	/api/checkouts/:id	Fetch one checkout
`GET`	/api/checkouts	List your checkouts (paginated)
`POST`	/api/refunds	Request a full or partial refund
`GET`	/api/refunds/:id	Fetch one refund request
`GET`	/api/refunds	List your refund requests (paginated)

Errors

Errors return an errors array:

{
  "errors": [
    {
      "status": "422",
      "code": "unprocessable_entity",
      "title": "Unprocessable Entity",
      "detail": "Validation failed: Amount has to be between R100.00 and R1,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:

{
  "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.float.co.za/api-docs). It’s regenerated on every deployment, so it always matches the running API.

Getting Started

Merchant Config

Checkouts

Refunds

Webhooks

Base URLs

Authentication

Conventions

Endpoints

Errors

Rate limits

OpenAPI specification

​Base URLs

​Authentication

​Conventions

​Endpoints

​Errors

​Rate limits

​Pagination

​OpenAPI specification

Base URLs

Authentication

Conventions

Endpoints

Errors

Rate limits

Pagination

OpenAPI specification