> ## Documentation Index
> Fetch the complete documentation index at: https://docs.float.co.za/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart
> Create a checkout and take a test payment in five minutes.
This guide takes you from zero to a completed sandbox payment. You need your sandbox **client secret** (see [Introduction → Getting credentials](/introduction#getting-credentials)).
Confirm your credentials work and see which instalment terms your account offers:
```bash theme={null}
curl https://uat-secure.float.co.za/api/config \
-H "Authorization: Bearer $FLOAT_CLIENT_SECRET"
```
```json theme={null}
{
"data": {
"id": "12345678-1111-1111-1111-1234567890ab",
"type": "merchants",
"attributes": {
"name": "South Park Cows Merch",
"rules": [
{ "from_amount": 10000, "to_amount": 100000000, "terms": [1, 2, 3, 4, 5, 6] }
]
}
}
}
```
Amounts are in **cents** — this merchant accepts checkouts from R100.00 to R1,000,000.00, payable over 1–6 instalments.
```bash cURL theme={null}
curl -X POST https://uat-secure.float.co.za/api/checkouts \
-H "Authorization: Bearer $FLOAT_CLIENT_SECRET" \
-H "Content-Type: application/json" \
-d '{
"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 }
]
}
}'
```
```ruby Ruby theme={null}
require "net/http"
require "json"
uri = URI("https://uat-secure.float.co.za/api/checkouts")
request = Net::HTTP::Post.new(uri, {
"Authorization" => "Bearer #{ENV.fetch('FLOAT_CLIENT_SECRET')}",
"Content-Type" => "application/json"
})
request.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" },
line_items: [{ name: "Clyde Frog", amount: 249_900, quantity: 1 }]
}
}.to_json
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
payment_url = JSON.parse(response.body).dig("data", "payment_url")
```
```javascript Node.js theme={null}
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",
},
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" },
line_items: [{ name: "Clyde Frog", amount: 249900, quantity: 1 }],
},
}),
});
const { data } = await response.json();
// data.payment_url
```
The response contains the hosted payment page URL:
```json theme={null}
{
"data": {
"id": "9b2f61c4-6c1e-4b7a-9a1d-3f2a8c0de111",
"payment_url": "https://uat-secure.float.co.za/payments/9b2f61c4-6c1e-4b7a-9a1d-3f2a8c0de111"
}
}
```
Store `data.id` (the **checkout ID**) against your order — you'll need it for status lookups and refunds.
Send the shopper's browser to `payment_url`. Float walks them through instalment selection, card details, and 3-D Secure.
When the payment completes (or is cancelled), Float:
1. **POSTs a signed callback** to your `notify_url` — this is your source of truth:
```json theme={null}
{
"status": "successful",
"amount": 249900,
"currency": "ZAR",
"client_reference_id": "order-1001",
"number_of_payments": 3
}
```
2. **Redirects the shopper** back to your `success_url` (or `cancel_url`).
Respond to the callback with a `2xx`. See [Callbacks](/guides/callbacks) for signature verification and the optional dynamic redirect.
Never fulfil an order based on the shopper arriving at your `success_url` — browsers get closed mid-redirect. Only fulfil when your `notify_url` receives `"status": "successful"`.
## Next steps
Add HMAC signatures — strongly recommended before go-live.
Verify signatures, be idempotent, control the final redirect.
Full and partial refunds via the API.
Everything to verify before switching to production.