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 | Required | Type | Description | Example |
|---|---|---|---|---|
| public_key | Y | String | Public API key for authentication (generated under integrations) | q9ZfVf7dT9g1uEJpXj7lZ0n2W8kYz4aLJc3p5Qw7s2A |
| mode | Y | ENUM | Payment mode (ONE_TIME, RECURRING, SAVE) | ONE_TIME |
| amount | Y | String | Payment amount | 100.00 |
| currency | N | String(3) | ISO 4217 currency code | ZAR |
| success_url | N | String | URL to redirect on successful payment | https://www.merchant.com/success |
| cancel_url | N | String | URL to redirect on cancelled payment | https://www.merchant.com/cancel |
| notify_url | N | String | Webhook URL for payment notifications | https://www.merchant.com/notify |
| order_id | N | String(32) | Either pass order_id OR order object of existing order, see orders | ord_abc123... |
| order_reference | N | String(35) | Reference identifier for new order, if left blank a new reference will be generated | ORD0045 |
| order_description | Y | String | Description of the order/item being purchased | My monthly subscription service |
| order_items_0_sku | N | String | Product SKU for first item | plan_pro_monthly |
| order_items_0_name | N | String | Product name for first item | Pro Plan (Monthly) |
| order_items_0_quantity | N | Integer | Item quantity for first item | 1 |
| order_items_0_unit_amount | N | String | Unit price for first item | 1200.00 |
| order_items_0_tax_amount | N | Number | Tax amount for first item | 0 |
| order_items_0_currency | N | String(3) | ISO 4217 currency code | ZAR |
| order_items_0_metadata_custom_field_1 | N | String | Custom metadata for first item | custom data 1 |
| order_items_0_metadata_custom_field_2 | N | String | Custom metadata for first item | custom data 2 |
| customer_fields | N | String | Comma-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_id | N | String(32) | Either pass customer_id OR customer object of existing customer, see customers | cus_abc123... |
| customer_reference | N | String(35) | Reference to identify a specific customer | CLN240919000001 |
| customer_company_name | N | String(64) | Company name if applicable | |
| customer_person_name | N | String(32) | Customer's first name | John |
| customer_person_surname | N | String(32) | Customer's surname | Doe |
| customer_client_type | N | ENUM | Client type (RESIDENT_INDIVIDUAL, NON_RESIDENT_INDIVIDUAL, DOMESTIC_COMPANY, FOREIGN_COMPANY, FINANCIAL_INSTITUTION) | RESIDENT_INDIVIDUAL |
| customer_id_type | N | ENUM | ID type (SAID, PASSPORT, TEMPORARY_RESIDENCE, COMPANY_REGISTRATION_NUMBER) | SAID |
| customer_id_number | N | String(13) | ID number | 900112.... |
| customer_email | N | String(128) | Customer email address | johndoe@mail.com |
| customer_contact_number | N | String(16) | Customer contact number | +27831234567 |
| customer_billing_address_line1 | N | String | Billing address line 1 | 1 Loop Street |
| customer_billing_address_line2 | N | String | Billing address line 2 | Floor 5 |
| customer_billing_address_city_or_town | N | String | Billing city | Cape Town |
| customer_billing_address_province_or_state | N | String | Billing province/state | Western Cape |
| customer_billing_address_postal_or_zip_code | N | String | Billing postal code | 8001 |
| customer_billing_address_country | N | String(2) | ISO 3166-1 alpha-2 country code | ZA |
| customer_shipping_contact_name | N | String | Shipping contact name | Jane Doe |
| customer_shipping_contact_number | N | String(16) | Shipping contact number | +27820000000 |
| customer_shipping_address_line1 | N | String | Shipping address line 1 | 1 Loop Street |
| customer_shipping_address_line2 | N | String | Shipping address line 2 | Floor 5 |
| customer_shipping_address_city_or_town | N | String | Shipping city | Cape Town |
| customer_shipping_address_province_or_state | N | String | Shipping province/state | Western Cape |
| customer_shipping_address_postal_or_zip_code | N | String | Shipping postal code | 8001 |
| customer_shipping_address_country | N | String(2) | ISO 3166-1 alpha-2 country code | ZA |
| customer_metadata_custom_field_1 | N | String | Custom metadata field 1 | custom data 1 |
| customer_metadata_custom_field_2 | N | String | Custom metadata field 2 | custom data 2 |
| payment_methods | N | String | Comma-separated list of payment methods to show: (CARD, ZAPPER, SNAPSCAN, APPLE_PAY, GOOGLE_PAY, SCAN_TO_PAY, 1VOUCHER, SCODE, MONEY_BADGER) | "CARD,ZAPPER" |
| payment_type | N | String(2) | Direct Debit (DB) or Pre-Authorization (PA), defaults to DB | DB |
| cards_save_cards | N | Boolean | Whether to save card for future use (for one-time payments) | true |
| cards_show_cards | N | Boolean | Whether to show previous saved cards for selection | true |
| notifications_send_invoice | N | Boolean | Send invoice to customer | true |
| notifications_send_confirmation_email | N | Boolean | Send confirmation email | true |
| notifications_confirmation_email_override | N | String | Override email for confirmations | accounts@example.com |
| customization.locale | N | ENUM | UI locale | EN_ZA |
| customization.theme | N | ENUM | UI theme: (LIGHT or DARK) | LIGHT |
| customization.type | N | ENUM | Display type: (PAGE or EMBED) | PAGE |
| customization_display_cancel_button | N | Boolean | Show cancel button on checkout | true |
| customization_display_total | N | Boolean | Display total amount | true |
| customization_display_cart | N | Boolean | Display cart details | true |
| customization_brand_primary | N | String | Primary brand color hex code | #00DC82 |
Checkout Page
Create a secure, customizable checkout page session to capture payments with cards, bank transfers, and other payment methods. Supports 3D Secure authentication, cards storage for recurring billing, order management, customer creation, and webhook notifications.
Payments
Process one-time and recurring payments across multiple methods including Pay-in, EFT Debit Orders, DebiCheck, Registered Mandates, and Card payments. Handle payment creation, status tracking, refunds, and webhook notifications.