Create a checkout

Create a checkout

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

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

POST

api

checkouts

Create a checkout

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

{
  "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

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

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":"eric.cartman@example.com","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: "eric.cartman@example.com",
      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: "eric.cartman@example.com",
      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'        => 'eric.cartman@example.com',
            '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": "eric.cartman@example.com",
            "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`

Intermediaries Get a checkout

⌘I

Getting Started

Merchant Config

Checkouts

Refunds

Webhooks

Request

Example

Response

Errors

​Request

​Example

​Response

​Errors

Request

Example

Response

Errors