Accepting payments

This guide covers everything a production custom integration needs. If you haven’t made your first API call yet, start with the Quickstart.

1. Show Float at checkout

Before offering Float as a payment option, make sure the cart total is inside your configured range. Fetch your config once and cache it (it rarely changes — and the endpoint is rate-limited to 5 requests/hour):

curl https://uat-secure.float.co.za/api/config \
  -H "Authorization: Bearer $FLOAT_CLIENT_SECRET"

Use rules to decide when to show the Float option and to render instalment messaging (e.g. cart total ÷ max term).

2. Create the checkout

When the shopper picks Float, create a checkout server-side:

POST /api/checkouts

{
  "checkout": {
    "amount": 249900,
    "currency": "ZAR",
    "client_reference_id": "order-1001",
    "notify_url": "https://example.com/float/notify",
    "success_url": "https://example.com/orders/1001/success",
    "cancel_url": "https://example.com/orders/1001/cancel",
    "customer": {
      "first_name": "Eric",
      "last_name": "Cartman",
      "email": "eric.cartman@example.com",
      "phone_number": "0101234567",
      "billing_address": "28201 E. Bonanza St, South Park"
    },
    "line_items": [
      { "name": "Clyde Frog", "amount": 249900, "quantity": 1 }
    ]
  }
}

Field-by-field details are in the API reference. Practical notes:

client_reference_id is your reconciliation key — use your order ID or cart session ID. It’s echoed back verbatim in the callback.
notify_url must be a publicly reachable HTTPS endpoint. It receives the payment result server-to-server.
success_url / cancel_url are browser redirect targets only — treat them as UX, not truth.
customer.email is required; pre-filling the rest reduces friction on Float’s page.
line_items appear on the shopper’s payment summary — include them for a better checkout experience.
Sign the request with X-Signature.

Persist the returned checkout id on your order before redirecting.

3. Redirect the shopper

Send the browser to the returned payment_url with a plain HTTP redirect. Don’t iframe it unless Float has explicitly enabled iframe integration for your account (this requires domain allowlisting on Float’s side).

4. Handle the callback

Float POSTs the result to your notify_url the moment the payment reaches a terminal state. This is the authoritative signal — implement it per the callbacks guide:

Verify the X-Signature header.
Look up the order by client_reference_id.
If successful: mark paid, fulfil. If cancelled: release the order.
Respond 2xx — optionally with { "redirect_url": "..." } to send the shopper to an order-specific confirmation page.

5. Handle the browser return

The shopper lands on your success_url or cancel_url (or the redirect_url you returned from the callback). Because the callback usually arrives first, the order state should already be settled — render it. If the callback hasn’t arrived yet (rare, but possible), poll your own order state briefly or call GET /api/checkouts/:id rather than showing an error.

6. Reconcile

For robustness, run a periodic reconciliation for orders stuck in a pending state older than ~1 hour:

curl https://uat-secure.float.co.za/api/checkouts/9b2f61c4-6c1e-4b7a-9a1d-3f2a8c0de111 \
  -H "Authorization: Bearer $FLOAT_CLIENT_SECRET"

{
  "data": {
    "id": "9b2f61c4-6c1e-4b7a-9a1d-3f2a8c0de111",
    "type": "checkouts",
    "attributes": {
      "amount": 249900,
      "currency": "ZAR",
      "status": "successful",
      "created_at": "2026-07-17T10:30:00Z"
    }
  }
}

A checkout still received after its ~30-minute payment session has lapsed will never complete — treat it as abandoned and create a new checkout if the shopper returns.

Edge cases worth handling

Shopper closes the browser after paying

The callback still fires — your notify_url is server-to-server. This is exactly why fulfilment must key off the callback, not the success_url.

Duplicate callbacks

Callbacks can be retried and duplicated. Make your handler idempotent: if the order is already marked paid, acknowledge with a 2xx and do nothing.

Amount changed after checkout creation

A Float checkout is fixed-amount. If the cart changes, abandon the old checkout and create a new one — never reuse a payment_url for a different total.

Shopper clicks back and pays twice

Guard on your side: if an order is already paid, don’t create another checkout for it. Use one client_reference_id per payable order state.

Getting Started

Concepts

Integration Guides

1. Show Float at checkout

2. Create the checkout

3. Redirect the shopper

4. Handle the callback

5. Handle the browser return

6. Reconcile

Edge cases worth handling

​1. Show Float at checkout

​2. Create the checkout

​3. Redirect the shopper

​4. Handle the callback

​5. Handle the browser return

​6. Reconcile

​Edge cases worth handling

1. Show Float at checkout

2. Create the checkout

3. Redirect the shopper

4. Handle the callback

5. Handle the browser return

6. Reconcile

Edge cases worth handling