Skip to main content

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