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
<form action="[path]/checkout/form" method="post">
<input type="hidden" name="public_key" value="q9ZfVf7dT9g1uEJpXj7lZ0n2W8kYz4aLJc3p5Qw7s2A">
<input type="hidden" name="mode" value="one-off"> <!-- 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 advanced example
<form action="[path]/checkout/form" method="post">
<input type="hidden" name="public_key" value="q9ZfVf7dT9g1uEJpXj7lZ0n2W8kYz4aLJc3p5Qw7s2A">
<input type="hidden" name="mode" value="one-off"> <!-- recurring or save -->
<input type="hidden" name="amount" value="100.00">
<input type="hidden" name="currency_lookups_id" value="loo_abc123...">
<!-- [optional: redirects] -->
<input type="hidden" name="return_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">
<!-- [optional: order details] -->
<!-- either pass the order_id or the order object -->
<input type="hidden" name="order_id" value="ord_12345">
<!-- create a new order -->
<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">
<!-- [optional: if no customer id or object is specified a form will show, here you can specify the fields to capture]-->
<input type="hidden" name="customer_fields" value="reference,id_number,email,contact_number,billing,shipping">
<!-- [optional: customer details] -->
<!-- either pass the customer_id or the customer object -->
<input type="hidden" name="customer_id" value="cus_abc123...">
<!-- 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_lookups_id" value="loo_abc123...">
<input type="hidden" name="customer_id_type_lookups_id" value="loo_abc123...">
<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_lookups_id" value="loo_abc123...">
<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_lookups_id" value="loo_abc123...">
<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_ids" value="pam_abc123...,pam_abc123...">
<!-- [optional: set the payment type: Direct Debit (Default), Pre-Authorization] -->
<input type="hidden" name="payment_type_lookups_id" value="loo_abc13...">
<!-- [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 | String | Payment mode - one-off, recurring, or save | one-off |
| amount | Y | String | Payment amount | 100.00 |
| currency_lookups_id | N | String(32) | Currency lookup ID | loo_abc123... |
| return_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) | ID of existing order (alternative to creating new order) | ord_12345 |
| 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_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) | ID of existing customer (alternative to creating new customer) | 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_lookups_id | N | String(32) | Client type lookup ID | loo_abc123... |
| customer_id_type_lookups_id | N | String(32) | ID type lookup (e.g. South African ID, passport) | loo_abc123... |
| 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_lookups_id | N | String(32) | Billing country lookup ID | loo_abc123... |
| 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_lookups_id | N | String(32) | Shipping country lookup ID | loo_abc123... |
| 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_ids | N | String | Comma-separated list of payment method IDs to show | pam_abc123...,pam_abc123... |
| payment_type_lookups_id | N | String(32) | Payment type lookup ID (Direct Debit, Pre-Authorization) | loo_abc13... |
| 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 | String | Checkout page locale | en-ZA |
| customization_theme | N | String | Checkout page theme - light or dark | light |
| customization_type | N | String | 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, 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.