> ## 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.

# Migrating from the legacy API

> Move from the v1 (plugin) API to the current Merchant API — field mappings and behavioural differences.

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](/guides/refunds)                           |

## Request field mapping

Legacy `POST /payment/checkout` → v2 [`POST /api/checkouts`](/api-reference/create-checkout):

| 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:

1. **Parse JSON** instead of form-encoded parameters.
2. **Verify the `X-Signature` header** instead of the `transaction_verify` token — see [Callbacks](/guides/callbacks#verifying-the-signature).
3. 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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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](/guides/testing-and-go-live).
  </Step>

  <Step title="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).
  </Step>

  <Step title="Decommission v1">
    Tell your Float contact so your v1 credentials can be revoked.
  </Step>
</Steps>