Migrate from V1

This guide walks you through everything that changed between V1 and V2 of the Kwik API so you can upgrade your integration with confidence. It is split into three parts:

• What's new — capabilities that did not exist in V1
• What changed — renamed endpoints and reshaped payloads
• Breaking changes — anything that will stop a V1 integration from working

TIP

V1 and V2 run side by side on different base paths, so you can migrate incrementally. Nothing in V1 changes when V2 is released — you upgrade endpoint by endpoint at your own pace.

At a glance

Base URL and authentication

The base path moved from 1.0 to 2.0:

- https://api.kwik.co.za/1.0/
+ https://api.kwik.co.za/2.0/

In V1 the staging and live environments used different hosts. In V2 there is a single base URL, and whether you hit test or live data is determined by the API key you authenticate with.

- # V1
- Staging: https://staging.app.kwik.co.za/1.0/
- Live:    https://api.kwik.co.za/1.0/
+ # V2 — one URL, test vs live decided by your API key
+ https://api.kwik.co.za/2.0/

Authentication is unchanged. V2 still uses Basic Authorization with a base64-encoded api_key:api_secret. See the Introduction for examples.

What's new

Products

V2 introduces a reusable Products catalogue. Instead of describing amounts inline on every request, you create products once and reference them from collections and checkouts. Products carry pricing, tax, and recurring billing configuration.

{
  "records": [{
    "name": "Generic Wooden Ball",
    "code": "PRD-606075",
    "price_excl": "2409.86",
    "is_tax": false,
    "pricing_type": "RECURRING",
    "billing_period": "MONTHLY"
  }]
}

Recipients

Recipients are reusable payout targets (the money-out equivalent of a customer). Create a recipient once and reference it by recipient_id on future payouts, rather than re-sending bank details every time.

Electronic Mandates

Electronic Mandates are hosted web pages that let new customers sign up, or existing customers add collections, without you building a form. The API lists your published pages and generates shareable, pre-fillable links.

Reorganised documentation

The flat V1 Reference section is now grouped by intent to make endpoints easier to find:

What's changed

Payments are now Collections

The single biggest change: the V1 Payments endpoint is now Collections. This better reflects that the endpoint pulls money in via debit orders.

- POST /payments/submit
+ POST /collections/submit

The request body was also reshaped:

• The batch array key changed from payments to records.
• Inline order / order_id is replaced by an items array that references products, with a top-level is_tax flag.

  {
    "batch_reference": "RFR23011",
-   "payments": [{
+   "records": [{
      "customer_id": "cus_abc123...",
      "bank_account_id": "ban_abc123...",
-     "order_id": "ord_12345",
-     "order": { "amount_subtotal": "1100.00", "amount_tax": "100.00" }
+     "is_tax": false,
+     "items": [{
+       "product_id": "pro_MsAXh25ajSIv4s6k52vQn",
+       "price": 45.00,
+       "qty": 1
+     }]
    }]
  }

See the full Collections reference for every field.

Checkout Page is now Checkout Link

- POST /checkout/page
+ POST /checkout/link

Checkout Link keeps the hosted-checkout concept but adds a richer, more flexible payload — a checkout type (such as CHOOSE_WHAT_TO_PAY), an item offer object, customization, notification.webhook_url, and optional invoice issuance.

Orders are now Products + items

V1 modelled amounts with Orders (amount_subtotal, amount_tax, amount_total, …). V2 replaces this with a reusable Products catalogue plus per-request items lines. Totals are derived from the items and the is_tax flag, so you no longer calculate and pass each amount field yourself.

Standardised records array

Across batch endpoints (collections, payouts, products, recipients) the request array is now consistently named records, replacing the per-endpoint names V1 used (payments, payouts, …).

- "payouts": [ ... ]
+ "records": [ ... ]

Payouts can reference recipients and customers

V1 payouts embedded the recipient inline. V2 payouts accept a recipient_id (or an inline recipient) and can also reference a customer_id for refunds, and use the standard records array.

Breaking changes

WARNING

The items below will break a V1 integration if not updated. Review each one before switching a flow to V2.

1. Endpoint paths

2. Request array keys

Any batch request that used a named array (for example payments or payouts) must now use records.

3. Collections payload

• Remove order / order_id; send an items array referencing product_id, price, and qty.
• Add the top-level is_tax flag; do not pass pre-computed amount_* totals.
• Supported payment methods for collections are EFT Debit Order, DebiCheck, and Registered Mandates. Card and Pay-in flows now run through Checkout Link rather than the collections endpoint.

4. Webhook events renamed

Money-in webhook events were renamed from payment.* to collection.*. Update both your event subscriptions and any handler switch logic.

The webhook_event enum changed correspondingly:

- PAYMENT_CREATED, PAYMENT_UPDATED
+ COLLECTION_CREATED, COLLECTION_UPDATED

All other events (customer.*, bank_account.*, mandate.*, transaction.*, checkout.*) are unchanged. See Webhooks.

5. AVS-R id_type enum values

The AVS-R verification endpoint now uses the full identity-type values used elsewhere in the API:

- SAID, PASSPORT, TEMPORARY_RESIDENCE, COMPANY_REGISTRATION_NUMBER
+ SOUTH_AFRICAN_ID, PASSPORT_NUMBER, TEMPORARY_RESIDENCE, COMPANY_REGISTRATION_NUMBER

6. Error message wording

The error response format and codes are unchanged, but the wording of a few payment-related codes now refers to collections (for example codes 012, 014, and 016). If you match on error_message text rather than error_code, update those checks. Matching on error_code continues to work. See Errors.

Migration checklist

• Point requests at the 2.0 base path.
• Confirm your API key targets the correct environment (test vs live).
• Rename payments → collections calls and switch the array key to records.
• Replace inline order data with products and items (+ is_tax).
• Move Card / Pay-in flows to Checkout Link.
• Update payout payloads to use records and (optionally) recipient_id.
• Re-subscribe webhooks to collection.* and update handler logic.
• Update AVS-R id_type values to the new enum.
• Re-test any logic that matches on error message text.