Authentication

Float uses two credentials, issued per merchant integration:

Credential	Used for	Where it appears
Client secret	Authenticating every API request	`Authorization: Bearer <client_secret>` header
Signing key	Signing your requests and verifying Float’s callbacks	`X-Signature` header (both directions)

Both values are secrets. Keep them server-side only — never embed them in web or mobile clients. If a secret leaks, contact Float immediately to rotate it.

Bearer authentication

Every API request must include your client secret as a Bearer token:

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

A missing or invalid token returns 401 Unauthorized:

{
  "errors": [
    {
      "status": "401",
      "code": "unauthorized",
      "title": "Unauthorized",
      "detail": "Please provide a valid Bearer token in the Authorization header."
    }
  ]
}

Request signing

Signing proves the request body wasn’t tampered with in transit and that it originated from you. It is optional to start, but strongly recommended — and required for production go-live.

Signing is sticky. The first time Float receives a correctly signed request from your integration, signing becomes mandatory for all subsequent mutating requests (POST /api/checkouts, POST /api/refunds). Unsigned requests after that point are rejected with 400 Bad Request. Enable signing in sandbox first and roll it out deliberately.

How to sign

Compute an HMAC-SHA512 digest of the exact raw JSON request body, keyed with your signing key, and Base64-encode it. Send it in the X-Signature header.

X-Signature: Base64( HMAC-SHA512( signing_key, raw_request_body ) )

require "openssl"

body = payload.to_json
signature = OpenSSL::HMAC.base64digest("SHA512", ENV.fetch("FLOAT_SIGNING_KEY"), body)

# Send `body` as the request body and `signature` in the X-Signature header.

const crypto = require("crypto");

const body = JSON.stringify(payload);
const signature = crypto
  .createHmac("sha512", process.env.FLOAT_SIGNING_KEY)
  .update(body)
  .digest("base64");

$body = json_encode($payload);
$signature = base64_encode(
    hash_hmac('sha512', $body, getenv('FLOAT_SIGNING_KEY'), true)
);

import base64, hashlib, hmac, json, os

body = json.dumps(payload, separators=(",", ":"))
signature = base64.b64encode(
    hmac.new(os.environ["FLOAT_SIGNING_KEY"].encode(), body.encode(), hashlib.sha512).digest()
).decode()

Always send compact JSON — never pretty-print. Float verifies your signature against a compact re-serialisation of your payload (key order preserved, whitespace stripped). A pretty-printed body will therefore never match, even if you signed exactly what you sent. The safe pattern: serialise compactly (the default in every example above), sign that string, and send that same string. A mismatch returns 400 Bad Request:

{
  "errors": [
    {
      "status": "400",
      "code": "bad_request",
      "title": "Bad Request",
      "detail": "Request signature does not match. The X-Signature header should match '<expected signature>'."
    }
  ]
}

The detail includes the signature Float expected — compare it to the one you computed to debug quickly.

Verifying Float’s callbacks

Float signs its callbacks to your notify_url with the same signing key and algorithm. Always verify before trusting the payload — see Callbacks → Verifying the signature.

Credential handling checklist

Store secrets in your secret manager or environment variables, never in source control.
Use separate credentials for sandbox and production.
Verify callback signatures with a constant-time comparison (Rack::Utils.secure_compare, crypto.timingSafeEqual, hash_equals).
Rotate immediately on suspected exposure via your Float account manager.

Getting Started

Concepts

Integration Guides

Bearer authentication

Request signing

How to sign

Verifying Float’s callbacks

Credential handling checklist

​Bearer authentication

​Request signing

​How to sign

​Verifying Float’s callbacks

​Credential handling checklist

Bearer authentication

Request signing

How to sign

Verifying Float’s callbacks

Credential handling checklist