Migrating from the legacy API

The legacy v1 API (the original POST /login + POST /payment/checkout plugin API) is being retired in favour of the current Merchant API documented on this site. The v2 API is simpler — no login step, cleaner payloads, signed callbacks — and all new features land there.

What changes at a glance

	Legacy v1	Current v2
Authentication	`POST /login` with `client_id` + `client_secret` + `merchant_id` → short-lived token	Static `Authorization: Bearer <client_secret>` on every call — no login step
Create payment	`POST /payment/checkout`	`POST /api/checkouts`
Integrity	None	HMAC-SHA512 `X-Signature` on requests and callbacks
Callback payload	Form-encoded `status`, `order_id`, `transaction_verify`, `number_of_payments`	Signed JSON `status`, `amount`, `currency`, `client_reference_id`, `number_of_payments`
Callback verification	Compare `transaction_verify` token	Verify `X-Signature` HMAC
Status values	`success` / `cancelled`	`successful` / `cancelled`
Status lookup / refunds	Not available	`GET /api/checkouts/:id`, full refunds API

Request field mapping

Legacy POST /payment/checkout → v2 POST /api/checkouts:

Legacy field	v2 field	Notes
`purchaseAmount`	`checkout.amount`	Still integer cents.
`currency`	`checkout.currency`	Unchanged.
`purchase.order_id`	`checkout.client_reference_id`	Echoed back in the callback.
`merchant.notify_url`	`checkout.notify_url`	Now receives signed JSON.
`merchant.return_url`	`checkout.success_url`	v2 adds a separate `cancel_url`.
—	`checkout.cancel_url`	New, required. Where cancelled shoppers land.
`customer.name`	`checkout.customer.first_name`
`customer.lastName`	`checkout.customer.last_name`
`customer.emailAddress`	`checkout.customer.email`	Required.
`customer.telephoneNumber`	`checkout.customer.phone_number`
`customer.billingAddress`	`checkout.customer.billing_address`
`purchase.items` (JSON-stringified)	`checkout.line_items` (real JSON array)	`description`→`name`, `price`→`amount`, `qty`→`quantity`. No more string-encoding.
`merchant.merchantReference`, `merchant.mode`, `purchase.purchaseDate`	—	Dropped. Environment is determined by the base URL; the merchant is identified by your Bearer token.

Callback changes

Your notify endpoint needs three updates:

Parse JSON instead of form-encoded parameters.
Verify the X-Signature header instead of the transaction_verify token — see Callbacks.
Match on status: "successful" (v1 sent "success"), and look up orders by client_reference_id (v1’s order_id).

The dynamic redirect works the same way conceptually, but the response field is now redirect_url (v1 used redirect).

Migration path

Get v2 credentials

Ask your Float contact to issue a v2 integration (client secret + signing key) for sandbox and production. Your v1 credentials keep working during the transition.

Build against sandbox

Point at https://uat-secure.float.co.za, implement the new checkout call and callback handler side by side with the old ones, and run the go-live checklist.

Cut over

Switch checkout creation to v2 in production. In-flight v1 payments continue to notify your old endpoint, so keep it alive until all v1 sessions have drained (a day is plenty).

Decommission v1

Tell your Float contact so your v1 credentials can be revoked.

Getting Started

Concepts

Integration Guides

What changes at a glance

Request field mapping

Callback changes

Migration path

​What changes at a glance

​Request field mapping

​Callback changes

​Migration path

What changes at a glance

Request field mapping

Callback changes

Migration path