Callbacks

Float’s signed server-to-server payment notifications: payload, verification, retries, and the dynamic redirect.

When a checkout reaches a terminal state, Float POSTs a JSON callback to the notify_url you supplied when creating the checkout. This callback is your source of truth for order state.

The payload

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

Field	Type	Description
status	string	successful or cancelled. Nothing else — a declined card lets the shopper retry, so there’s no failed.
amount	integer	The checkout amount in cents, as originally submitted.
currency	string	ISO 4217 code (ZAR).
client_reference_id	string	Echoed verbatim from your checkout request. Use it to find the order.
number_of_payments	integer	The instalment term the shopper selected.

Headers:

Content-Type: application/json
X-Signature: <Base64 HMAC-SHA512 of the raw body>

Verifying the signature

Float signs the raw JSON body with your signing key (the same one you use for request signing). Verify every callback before trusting it:

Ruby (Rails)

class FloatCallbacksController < ApplicationController
  skip_before_action :verify_authenticity_token

  def create
    raw_body  = request.body.read
    expected  = OpenSSL::HMAC.base64digest("SHA512", ENV.fetch("FLOAT_SIGNING_KEY"), raw_body)
    signature = request.headers["X-Signature"].to_s

    return head :unauthorized unless ActiveSupport::SecurityUtils.secure_compare(expected, signature)

    payload = JSON.parse(raw_body)
    order = Order.find_by!(reference: payload["client_reference_id"])
    order.mark_paid!(instalments: payload["number_of_payments"]) if payload["status"] == "successful"
    order.mark_cancelled! if payload["status"] == "cancelled"

    render json: { redirect_url: order_confirmation_url(order) }
  end
end

const crypto = require("crypto");
const express = require("express");
const app = express();

app.post("/float/notify", express.raw({ type: "application/json" }), (req, res) => {
  const expected = crypto
    .createHmac("sha512", process.env.FLOAT_SIGNING_KEY)
    .update(req.body)
    .digest("base64");
  const signature = req.get("X-Signature") || "";

  const valid =
    expected.length === signature.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
  if (!valid) return res.sendStatus(401);

  const payload = JSON.parse(req.body);
  // ...update the order by payload.client_reference_id...

  res.json({ redirect_url: `https://example.com/orders/${payload.client_reference_id}/confirmed` });
});

$rawBody   = file_get_contents('php://input');
$expected  = base64_encode(hash_hmac('sha512', $rawBody, getenv('FLOAT_SIGNING_KEY'), true));
$signature = $_SERVER['HTTP_X_SIGNATURE'] ?? '';

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit;
}

$payload = json_decode($rawBody, true);
// ...update the order by $payload['client_reference_id']...

header('Content-Type: application/json');
echo json_encode(['redirect_url' => 'https://example.com/orders/confirmed']);

Verify against the raw request body bytes, not a re-serialised parse of them, and use a constant-time comparison. Reject anything that doesn’t verify.

Responding

• Return any 2xx status to acknowledge. Anything else counts as a failed delivery and triggers retries.
• Respond fast (well under 10 seconds). Do heavy work — emails, ERP syncs — asynchronously after acknowledging.

Dynamic redirect (optional)

If your 2xx response body is JSON containing a redirect_url, Float sends the shopper’s browser there instead of your static success_url/cancel_url:

{ "redirect_url": "https://example.com/orders/1001/confirmed?token=abc123" }

This lets you land the shopper on an order-specific, authenticated confirmation page. Notes:

• Only honoured on the initial synchronous delivery (the one made while the shopper is waiting on Float’s page). Retried deliveries can’t affect a redirect that already happened.
• Omit the field (or return an empty body) to use your static URLs — that’s perfectly fine.

Delivery and retries

• The first delivery happens synchronously while the shopper is still on Float’s payment page.
• If it fails (timeout, non-2xx, network error), Float retries in the background — up to 18 attempts at ~10-minute intervals (~3 hours).
• The shopper is still redirected using your static URLs even when the callback fails, so your success_url page must tolerate the order not being marked paid yet.
• After retries are exhausted, Float’s team is alerted and can re-trigger the notification manually. Your safety net is reconciliation via GET /api/checkouts/:id.

Idempotency

Duplicate deliveries are possible (retry races, manual re-triggers). Key your handler on client_reference_id + status: if the order is already in the target state, return 2xx without side effects.

Endpoint requirements

• Public HTTPS with a valid certificate — SSL errors are a common cause of failed deliveries and will page Float’s support team.
• No authentication challenge (signature verification replaces it).
• If your infrastructure requires IP allowlisting, ask Float support about static egress IPs.

Testing your handler locally

Simulate a callback with curl (signature computed with your sandbox signing key):

BODY='{"status":"successful","amount":249900,"currency":"ZAR","client_reference_id":"order-1001","number_of_payments":3}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha512 -hmac "$FLOAT_SIGNING_KEY" -binary | base64)

curl -X POST https://localhost:3000/float/notify \
  -H "Content-Type: application/json" \
  -H "X-Signature: $SIG" \
  -d "$BODY"

For end-to-end sandbox tests, expose your local server with a tunnel (ngrok, Cloudflare Tunnel) and use the tunnel URL as notify_url.