Create a checkout

POST /api/checkouts — create a payment session and get the hosted payment URL.

POST /api/checkouts

Create a checkout

cURL

curl --request POST \
  --url https://uat-secure.float.co.za/api/checkouts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "checkout": {},
  "checkout.amount": 123,
  "checkout.currency": "<string>",
  "checkout.client_reference_id": "<string>",
  "checkout.notify_url": {},
  "checkout.success_url": {},
  "checkout.cancel_url": {},
  "checkout.customer": {
    "email": {},
    "first_name": "<string>",
    "last_name": "<string>",
    "phone_number": "<string>",
    "billing_address": "<string>"
  },
  "checkout.line_items": [
    {
      "name": "<string>",
      "amount": 123,
      "quantity": 123
    }
  ]
}
'

import requests

url = "https://uat-secure.float.co.za/api/checkouts"

payload = {
    "checkout": {},
    "checkout.amount": 123,
    "checkout.currency": "<string>",
    "checkout.client_reference_id": "<string>",
    "checkout.notify_url": {},
    "checkout.success_url": {},
    "checkout.cancel_url": {},
    "checkout.customer": {
        "email": {},
        "first_name": "<string>",
        "last_name": "<string>",
        "phone_number": "<string>",
        "billing_address": "<string>"
    },
    "checkout.line_items": [
        {
            "name": "<string>",
            "amount": 123,
            "quantity": 123
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    checkout: {},
    'checkout.amount': 123,
    'checkout.currency': '<string>',
    'checkout.client_reference_id': '<string>',
    'checkout.notify_url': {},
    'checkout.success_url': {},
    'checkout.cancel_url': {},
    'checkout.customer': {
      email: {},
      first_name: '<string>',
      last_name: '<string>',
      phone_number: '<string>',
      billing_address: '<string>'
    },
    'checkout.line_items': [{name: '<string>', amount: 123, quantity: 123}]
  })
};

fetch('https://uat-secure.float.co.za/api/checkouts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://uat-secure.float.co.za/api/checkouts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'checkout' => [
        
    ],
    'checkout.amount' => 123,
    'checkout.currency' => '<string>',
    'checkout.client_reference_id' => '<string>',
    'checkout.notify_url' => [
        
    ],
    'checkout.success_url' => [
        
    ],
    'checkout.cancel_url' => [
        
    ],
    'checkout.customer' => [
        'email' => [
                
        ],
        'first_name' => '<string>',
        'last_name' => '<string>',
        'phone_number' => '<string>',
        'billing_address' => '<string>'
    ],
    'checkout.line_items' => [
        [
                'name' => '<string>',
                'amount' => 123,
                'quantity' => 123
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://uat-secure.float.co.za/api/checkouts"

	payload := strings.NewReader("{\n  \"checkout\": {},\n  \"checkout.amount\": 123,\n  \"checkout.currency\": \"<string>\",\n  \"checkout.client_reference_id\": \"<string>\",\n  \"checkout.notify_url\": {},\n  \"checkout.success_url\": {},\n  \"checkout.cancel_url\": {},\n  \"checkout.customer\": {\n    \"email\": {},\n    \"first_name\": \"<string>\",\n    \"last_name\": \"<string>\",\n    \"phone_number\": \"<string>\",\n    \"billing_address\": \"<string>\"\n  },\n  \"checkout.line_items\": [\n    {\n      \"name\": \"<string>\",\n      \"amount\": 123,\n      \"quantity\": 123\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://uat-secure.float.co.za/api/checkouts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"checkout\": {},\n  \"checkout.amount\": 123,\n  \"checkout.currency\": \"<string>\",\n  \"checkout.client_reference_id\": \"<string>\",\n  \"checkout.notify_url\": {},\n  \"checkout.success_url\": {},\n  \"checkout.cancel_url\": {},\n  \"checkout.customer\": {\n    \"email\": {},\n    \"first_name\": \"<string>\",\n    \"last_name\": \"<string>\",\n    \"phone_number\": \"<string>\",\n    \"billing_address\": \"<string>\"\n  },\n  \"checkout.line_items\": [\n    {\n      \"name\": \"<string>\",\n      \"amount\": 123,\n      \"quantity\": 123\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://uat-secure.float.co.za/api/checkouts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"checkout\": {},\n  \"checkout.amount\": 123,\n  \"checkout.currency\": \"<string>\",\n  \"checkout.client_reference_id\": \"<string>\",\n  \"checkout.notify_url\": {},\n  \"checkout.success_url\": {},\n  \"checkout.cancel_url\": {},\n  \"checkout.customer\": {\n    \"email\": {},\n    \"first_name\": \"<string>\",\n    \"last_name\": \"<string>\",\n    \"phone_number\": \"<string>\",\n    \"billing_address\": \"<string>\"\n  },\n  \"checkout.line_items\": [\n    {\n      \"name\": \"<string>\",\n      \"amount\": 123,\n      \"quantity\": 123\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

200

{
  "data.id": {},
  "data.payment_url": {}
}

Creates a checkout and returns the payment_url to redirect your shopper to. See the accepting payments guide for how this call fits into the full flow.

Rate limited to 1 request per second — comfortably above normal checkout traffic, but batch jobs should space their calls.

Request

Headers: Authorization: Bearer <client_secret>, Content-Type: application/json, and X-Signature (request signing).

checkout · object · required

Wrapper object for all checkout fields.

checkout.amount · integer · required

Total payable amount in cents. Must fall inside a band in your merchant config rules, otherwise 422.

checkout.currency · string · required

ISO 4217 code. Must match your merchant territory currency: ZAR.

checkout.client_reference_id · string · required

Your identifier for this order or cart session. Echoed verbatim in the callback — use it to reconcile.

checkout.notify_url · string (url) · required

Public HTTPS endpoint that receives the signed payment-result callback.

checkout.success_url · string (url) · required

Where the shopper’s browser is sent after successful payment (unless your callback response supplies a dynamic redirect_url).

checkout.cancel_url · string (url) · required

Where the shopper’s browser is sent if they cancel.

checkout.customer · object · required

The shopper. Pre-fill as much as you have — it reduces friction on the payment page.

Show customer fields

email · string (email) · required

Shopper’s email address.

first_name · string

Max 255 characters.

last_name · string

Max 255 characters.

phone_number · string

Must match ^[+0-9][0-9.()/-]{7,25}$ — digits with optional leading + and common separators.

billing_address · string

Free-text billing address.

checkout.line_items · array

Cart contents, shown on the shopper’s payment summary.

Show line item fields

name · string · required

Item display name.

amount · integer · required

Unit price in cents.

quantity · integer · required

Number of units.

Example

cURL

BODY='{"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":"[e-mail]","phone_number":"0101234567"},"line_items":[{"name":"Clyde Frog","amount":249900,"quantity":1}]}}'

SIGNATURE=$(printf '%s' "$BODY" | openssl dgst -sha512 -hmac "$FLOAT_SIGNING_KEY" -binary | base64)

curl -X POST https://uat-secure.float.co.za/api/checkouts \
  -H "Authorization: Bearer $FLOAT_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -H "X-Signature: $SIGNATURE" \
  -d "$BODY"

require "net/http"
require "openssl"
require "json"

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: "[e-mail]",
      phone_number: "0101234567"
    },
    line_items: [{ name: "Clyde Frog", amount: 249_900, quantity: 1 }]
  }
}.to_json

uri = URI("https://uat-secure.float.co.za/api/checkouts")
response = Net::HTTP.post(
  uri,
  body,
  "Authorization" => "Bearer #{ENV.fetch('FLOAT_CLIENT_SECRET')}",
  "Content-Type"  => "application/json",
  "X-Signature"   => OpenSSL::HMAC.base64digest("SHA512", ENV.fetch("FLOAT_SIGNING_KEY"), body)
)

payment_url = JSON.parse(response.body).dig("data", "payment_url")

const crypto = require("crypto");

const 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: "[e-mail]",
      phone_number: "0101234567",
    },
    line_items: [{ name: "Clyde Frog", amount: 249900, quantity: 1 }],
  },
});

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

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",
    "X-Signature": signature,
  },
  body,
});

const { data } = await response.json();
// redirect the shopper to data.payment_url

$body = json_encode([
    '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'        => '[e-mail]',
            'phone_number' => '0101234567',
        ],
        'line_items' => [
            ['name' => 'Clyde Frog', 'amount' => 249900, 'quantity' => 1],
        ],
    ],
]);

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

$ch = curl_init('https://uat-secure.float.co.za/api/checkouts');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $body,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('FLOAT_CLIENT_SECRET'),
        'Content-Type: application/json',
        'X-Signature: ' . $signature,
    ],
]);

$response = json_decode(curl_exec($ch), true);
$paymentUrl = $response['data']['payment_url'];

import base64, hashlib, hmac, json, os
import requests

body = json.dumps({
    "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": "[e-mail]",
            "phone_number": "0101234567",
        },
        "line_items": [{"name": "Clyde Frog", "amount": 249900, "quantity": 1}],
    }
}, separators=(",", ":"))

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

response = requests.post(
    "https://uat-secure.float.co.za/api/checkouts",
    data=body,
    headers={
        "Authorization": f"Bearer {os.environ['FLOAT_CLIENT_SECRET']}",
        "Content-Type": "application/json",
        "X-Signature": signature,
    },
)

payment_url = response.json()["data"]["payment_url"]

Response

200

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

data.id · string (uuid)

The checkout ID. Persist it — it’s required for status lookups and refunds.

data.payment_url · string (url)

The hosted payment page. Redirect the shopper here. The session is valid for roughly 30 minutes.

Errors

HTTP	When	Example detail
400	Signature mismatch	Request signature does not match...
401	Bad Bearer token
422	Validation failure	Validation failed: Amount has to be between R100.00 and R1,000,000.00
422	Wrong currency for territory	Currency must match merchant territory currency ZAR