Refunds

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

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

{
  "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.

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

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.

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`.
`404`	Unknown `checkout_id`	Verify you stored the checkout `id` (not your own order ID).
`400`	Signature mismatch	See request signing.
`429`	Rate limited (1 request/second on create)	Back off and retry.

Getting Started

Concepts

Integration Guides

Creating a refund

Refund lifecycle

Constraints

Cancelling vs refunding

Common errors

​Creating a refund

​Refund lifecycle

​Constraints

​Cancelling vs refunding

​Common errors

Creating a refund

Refund lifecycle

Constraints

Cancelling vs refunding

Common errors