Quickstart

This guide takes you from zero to a completed sandbox payment. You need your sandbox client secret (see Introduction → Getting credentials).

Check your merchant configuration

Confirm your credentials work and see which instalment terms your account offers:

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

{
  "data": {
    "id": "12345678-1111-1111-1111-1234567890ab",
    "type": "merchants",
    "attributes": {
      "name": "South Park Cows Merch",
      "rules": [
        { "from_amount": 10000, "to_amount": 100000000, "terms": [1, 2, 3, 4, 5, 6] }
      ]
    }
  }
}

Amounts are in cents — this merchant accepts checkouts from R100.00 to R1,000,000.00, payable over 1–6 instalments.

Create a checkout

curl -X POST https://uat-secure.float.co.za/api/checkouts \
  -H "Authorization: Bearer $FLOAT_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
      },
      "line_items": [
        { "name": "Clyde Frog", "amount": 249900, "quantity": 1 }
      ]
    }
  }'

require "net/http"
require "json"

uri = URI("https://uat-secure.float.co.za/api/checkouts")
request = Net::HTTP::Post.new(uri, {
  "Authorization" => "Bearer #{ENV.fetch('FLOAT_CLIENT_SECRET')}",
  "Content-Type"  => "application/json"
})
request.body = {
  checkout: {
    amount: 249_900,
    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" },
    line_items: [{ name: "Clyde Frog", amount: 249_900, quantity: 1 }]
  }
}.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
payment_url = JSON.parse(response.body).dig("data", "payment_url")

const response = await fetch("https://uat-secure.float.co.za/api/checkouts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FLOAT_CLIENT_SECRET}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    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" },
      line_items: [{ name: "Clyde Frog", amount: 249900, quantity: 1 }],
    },
  }),
});
const { data } = await response.json();
// data.payment_url

The response contains the hosted payment page URL:

{
  "data": {
    "id": "9b2f61c4-6c1e-4b7a-9a1d-3f2a8c0de111",
    "payment_url": "https://uat-secure.float.co.za/payments/9b2f61c4-6c1e-4b7a-9a1d-3f2a8c0de111"
  }
}

Store data.id (the checkout ID) against your order — you’ll need it for status lookups and refunds.

Redirect the shopper

Send the shopper’s browser to payment_url. Float walks them through instalment selection, card details, and 3-D Secure.

Receive the result

When the payment completes (or is cancelled), Float:

POSTs a signed callback to your notify_url — this is your source of truth:

{
  "status": "successful",
  "amount": 249900,
  "currency": "ZAR",
  "client_reference_id": "order-1001",
  "number_of_payments": 3
}

Redirects the shopper back to your success_url (or cancel_url).

Respond to the callback with a 2xx. See Callbacks for signature verification and the optional dynamic redirect.

Never fulfil an order based on the shopper arriving at your success_url — browsers get closed mid-redirect. Only fulfil when your notify_url receives "status": "successful".

Next steps

Sign your requests

Add HMAC signatures — strongly recommended before go-live.

Handle callbacks properly

Verify signatures, be idempotent, control the final redirect.

Refunds

Full and partial refunds via the API.

Go-live checklist

Everything to verify before switching to production.

Getting Started

Concepts

Integration Guides

Next steps

Sign your requests

Handle callbacks properly

Refunds

Go-live checklist

​Next steps

Sign your requests

Handle callbacks properly

Refunds

Go-live checklist

Next steps