Reference

Checkout Form

HTML form-based integration for creating secure checkout sessions without JavaScript. Supports order management, customer creation, payment customization, and redirect handling with simple form submissions.

Form (Basic example)

Basic example of the required fields

<form action="[path]/checkout/form" method="post">
  <input type="hidden" name="public_key" value="<INSERT YOUR PUBLIC KEY>">
  <input type="hidden" name="mode" value="ONE_TIME"> <!-- RECURRING or SAVE -->
  <input type="hidden" name="amount" value="100.00">
  <input type="hidden" name="order_description" value="My monthly subscription service">

  <input type="submit">
</form>

Form (Save card)

Redirect to a page to save the customer's card for future recurring payments or as a backup card. A R2 will be charged to verify that the card is valid.

<form action="[path]/checkout/form" method="post">
  <input type="hidden" name="public_key" value="<INSERT YOUR PUBLIC KEY>">
  <input type="hidden" name="mode" value="SAVE">
  <!-- if no customer details passed then a form will show on the payment link to create a customer -->
</form>

Form (Advanced example)

Advanced example with all the fields

<form action="[path]/checkout/form" method="post">
  <input type="hidden" name="public_key" value="<INSERT YOUR PUBLIC KEY>">
  <input type="hidden" name="mode" value="ONE_TIME"> <!-- recurring or save -->
  <input type="hidden" name="amount" value="100.00">
  <input type="hidden" name="currency" value="ZAR">

  <!-- [optional: redirects] -->
  <input type="hidden" name="success_url" value="https://www.merchant.com/success">
  <input type="hidden" name="cancel_url" value="https://www.merchant.com/cancel">
  <input type="hidden" name="notify_url" value="https://www.merchant.com/notify">

  <!-- [options for order records] -->
  <!-- [option 1: use the order_id of an existing order record] -->
  <input type="hidden" name="order_id" value="ord_12345">
  <!-- [option 2: use the order_description field to create an order, if no order_reference passed then one will be created] -->
  <input type="hidden" name="order_reference" value="ORD0045">
  <input type="hidden" name="order_description" value="Monthly plan + setup">
  <input type="hidden" name="order_items_0_sku" value="plan_pro_monthly">
  <input type="hidden" name="order_items_0_name" value="Pro Plan (Monthly)">
  <input type="hidden" name="order_items_0_quantity" value="1">
  <input type="hidden" name="order_items_0_unit_amount" value="100.00">
  <input type="hidden" name="order_items_0_tax_amount" value="0">
  <input type="hidden" name="order_items_0_metadata_custom_field_1" value="custom data 1">
  <input type="hidden" name="order_items_0_metadata_custom_field_2" value="custom data 2">

  

  <!-- [options for customer records] -->
  <!-- [option 1: use the customer_id of an existing customer record] -->
  <input type="hidden" name="customer_id" value="cus_abc123...">
  <!-- [option 2: if no customer id or customer object is passed then a form will show, here you can specify the fields to capture, name and surname will always show] -->
  <input type="hidden" name="customer_fields" value="reference,id_number,email,contact_number,billing,shipping">
  <!-- [option 3: create a new customer] -->
  <input type="hidden" name="customer_reference" value="CLN240919000001">
  <input type="hidden" name="customer_company_name" value="">
  <input type="hidden" name="customer_person_name" value="John">
  <input type="hidden" name="customer_person_surname" value="Doe">
  <input type="hidden" name="customer_client_type" value="RESIDENT_INDIVIDUAL">
  <input type="hidden" name="customer_id_type" value="SAID">
  <input type="hidden" name="customer_id_number" value="900112....">
  <input type="hidden" name="customer_email" value="johndoe@mail.com">
  <input type="hidden" name="customer_contact_number" value="+27831234567">
  <input type="hidden" name="customer_billing_address_line1" value="1 Loop Street">
  <input type="hidden" name="customer_billing_address_line2" value="Floor 5">
  <input type="hidden" name="customer_billing_address_city_or_town" value="Cape Town">
  <input type="hidden" name="customer_billing_address_province_or_state" value="Western Cape">
  <input type="hidden" name="customer_billing_address_postal_or_zip_code" value="8001">
  <input type="hidden" name="customer_billing_address_country" value="ZA">
  <input type="hidden" name="customer_shipping_contact_name" value="Jane Doe">
  <input type="hidden" name="customer_shipping_contact_number" value="+27820000000">
  <input type="hidden" name="customer_shipping_address_line1" value="1 Loop Street">
  <input type="hidden" name="customer_shipping_address_line2" value="Floor 5">
  <input type="hidden" name="customer_shipping_address_city_or_town" value="Cape Town">
  <input type="hidden" name="customer_shipping_address_province_or_state" value="Western Cape">
  <input type="hidden" name="customer_shipping_address_postal_or_zip_code" value="8001">
  <input type="hidden" name="customer_shipping_address_country" value="ZA">
  <input type="hidden" name="customer_metadata_custom_field_1" value="custom data 1">
  <input type="hidden" name="customer_metadata_custom_field_2" value="custom data 2"> 

  <!-- [optional: populate to specify payment methods to show else all will show] -->
  <input type="hidden" name="payment_methods" value="CARD,ZAPPER">
  <!-- [optional: set the payment type: Direct Debit (Default), Pre-Authorization] -->
  <input type="hidden" name="payment_type" value="DB">

  <!-- [optional: save cards for one-time payments] -->
  <input type="hidden" name="cards_save_cards" value="true">
  <!-- [optional: show previous saved cards for use to select from]-->
  <input type="hidden" name="cards_show_cards" value="true">

  <!-- [optional: notifications] -->
  <input type="hidden" name="notifications_send_invoice" value="true">
  <input type="hidden" name="notifications_send_confirmation_email" value="true">
  <input type="hidden" name="notifications_confirmation_email_override" value="accounts@example.com">

  <!-- [optional: customization] -->
  <input type="hidden" name="customization_locale" value="EN_ZA">
  <input type="hidden" name="customization_theme" value="LIGHT">
  <input type="hidden" name="customization_type" value="PAGE">
  <input type="hidden" name="customization_display_cancel_button" value="true">
  <input type="hidden" name="customization_display_total" value="true">
  <input type="hidden" name="customization_display_cart" value="true">
  <input type="hidden" name="customization_brand_primary" value="#00DC82">

  <input type="submit">
</form>

Request Parameters

Field
RequiredType
Description
Example
public_keyYStringPublic API key for authentication (generated under integrations)q9ZfVf7dT9g1uEJpXj7lZ0n2W8kYz4aLJc3p5Qw7s2A
modeYENUMPayment mode (ONE_TIME, RECURRING, SAVE)ONE_TIME
amountYStringPayment amount100.00
currencyNString(3)ISO 4217 currency codeZAR
success_urlNStringURL to redirect on successful paymenthttps://www.merchant.com/success
cancel_urlNStringURL to redirect on cancelled paymenthttps://www.merchant.com/cancel
notify_urlNStringWebhook URL for payment notificationshttps://www.merchant.com/notify
order_idNString(32)Either pass order_id OR order object of existing order, see ordersord_abc123...
order_referenceNString(35)Reference identifier for new order, if left blank a new reference will be generatedORD0045
order_descriptionYStringDescription of the order/item being purchasedMy monthly subscription service
order_items_0_skuNStringProduct SKU for first itemplan_pro_monthly
order_items_0_nameNStringProduct name for first itemPro Plan (Monthly)
order_items_0_quantityNIntegerItem quantity for first item1
order_items_0_unit_amountNStringUnit price for first item1200.00
order_items_0_tax_amountNNumberTax amount for first item0
order_items_0_currencyNString(3)ISO 4217 currency codeZAR
order_items_0_metadata_custom_field_1NStringCustom metadata for first itemcustom data 1
order_items_0_metadata_custom_field_2NStringCustom metadata for first itemcustom data 2
customer_fieldsNStringComma-separated list of customer fields to capture in form (if no customer_id or customer object is specified)reference,id_number,email,contact_number,billing,shipping
customer_idNString(32)Either pass customer_id OR customer object of existing customer, see customerscus_abc123...
customer_referenceNString(35)Reference to identify a specific customerCLN240919000001
customer_company_nameNString(64)Company name if applicable
customer_person_nameNString(32)Customer's first nameJohn
customer_person_surnameNString(32)Customer's surnameDoe
customer_client_typeNENUMClient type (RESIDENT_INDIVIDUAL, NON_RESIDENT_INDIVIDUAL, DOMESTIC_COMPANY, FOREIGN_COMPANY, FINANCIAL_INSTITUTION)RESIDENT_INDIVIDUAL
customer_id_typeNENUMID type (SAID, PASSPORT, TEMPORARY_RESIDENCE, COMPANY_REGISTRATION_NUMBER)SAID
customer_id_numberNString(13)ID number900112....
customer_emailNString(128)Customer email addressjohndoe@mail.com
customer_contact_numberNString(16)Customer contact number+27831234567
customer_billing_address_line1NStringBilling address line 11 Loop Street
customer_billing_address_line2NStringBilling address line 2Floor 5
customer_billing_address_city_or_townNStringBilling cityCape Town
customer_billing_address_province_or_stateNStringBilling province/stateWestern Cape
customer_billing_address_postal_or_zip_codeNStringBilling postal code8001
customer_billing_address_countryNString(2)ISO 3166-1 alpha-2 country codeZA
customer_shipping_contact_nameNStringShipping contact nameJane Doe
customer_shipping_contact_numberNString(16)Shipping contact number+27820000000
customer_shipping_address_line1NStringShipping address line 11 Loop Street
customer_shipping_address_line2NStringShipping address line 2Floor 5
customer_shipping_address_city_or_townNStringShipping cityCape Town
customer_shipping_address_province_or_stateNStringShipping province/stateWestern Cape
customer_shipping_address_postal_or_zip_codeNStringShipping postal code8001
customer_shipping_address_countryNString(2)ISO 3166-1 alpha-2 country codeZA
customer_metadata_custom_field_1NStringCustom metadata field 1custom data 1
customer_metadata_custom_field_2NStringCustom metadata field 2custom data 2
payment_methodsNStringComma-separated list of payment methods to show: (CARD, ZAPPER, SNAPSCAN, APPLE_PAY, GOOGLE_PAY, SCAN_TO_PAY, 1VOUCHER, SCODE, MONEY_BADGER)"CARD,ZAPPER"
payment_typeNString(2)Direct Debit (DB) or Pre-Authorization (PA), defaults to DBDB
cards_save_cardsNBooleanWhether to save card for future use (for one-time payments)true
cards_show_cardsNBooleanWhether to show previous saved cards for selectiontrue
notifications_send_invoiceNBooleanSend invoice to customertrue
notifications_send_confirmation_emailNBooleanSend confirmation emailtrue
notifications_confirmation_email_overrideNStringOverride email for confirmationsaccounts@example.com
customization.localeNENUMUI localeEN_ZA
customization.themeNENUMUI theme: (LIGHT or DARK)LIGHT
customization.typeNENUMDisplay type: (PAGE or EMBED)PAGE
customization_display_cancel_buttonNBooleanShow cancel button on checkouttrue
customization_display_totalNBooleanDisplay total amounttrue
customization_display_cartNBooleanDisplay cart detailstrue
customization_brand_primaryNStringPrimary brand color hex code#00DC82

Copyright © 2025 Kwik