Skip to main content
When a checkout reaches a final state, Float sends a single POST to the notify_url you supplied on create checkout. This page is the wire contract; the callbacks guide covers handler implementation, verification code, and local testing.

​
Request

Method: POST · Content-Type: application/json

​
Body

​
status
string
required
successful or cancelled. There is no failed — the shopper can retry on the hosted page until they succeed or abandon, so a failed attempt is not final.
​
amount
integer
required
The full payable amount in cents, exactly as sent when the checkout was created.
​
currency
string
required
ISO 4217 code (ZAR), as sent on the checkout.
​
client_reference_id
string
required
Your reference from the checkout request, echoed verbatim. Use this to find the order on your side.
​
number_of_payments
integer
required
The instalment term the shopper selected on the payment page (1 = once-off).
The callback does not include the checkout ID. Store the mapping client_reference_id → checkout_id when you create the checkout — you’ll need the ID for status lookups and refunds.

​
Your response

Respond 2xx quickly (do fulfilment work async). Any 2xx counts as delivered, but returning JSON unlocks an optional feature:
​
redirect_url
string (url)
If present and non-empty in your JSON response, Float sends the shopper’s browser here instead of the checkout’s success_url / cancel_url — useful for order-specific confirmation pages created during callback handling.
Return {} (or anything else with a 2xx) to use the default redirect.

​
Delivery semantics

Callbacks can be missed (your endpoint down for longer than the retry window). Reconcile any order still pending after ~1 hour with GET /api/checkouts/:id — never leave paid orders unfulfilled because a webhook was dropped.