Skip to main content
Float uses two credentials, issued per merchant integration:
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:
A missing or invalid token returns 401 Unauthorized:

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.
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:
The response does not include the signature Float expected. To debug, log the exact string you signed and the exact body you sent, and check they are identical.

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.