How Float works

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

The payment flow

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.

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.

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); 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 rules.

Instalment terms

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

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