Reference
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.
Request
Request to get a checkout page session with URL
Path
POST /checkout/page
Request Body
{
"mode": "one-off", // recurring or save
"amount": "1200.00",
"currency": "ZAR",
// either pass the order_id or the order object
"order_id": "ord_12345",
// create a new order
"order": {
"reference": "ORD0045",
"description": "Monthly plan + setup",
"items": [
{
"sku": "plan_pro_monthly",
"name": "Pro Plan (Monthly)",
"quantity": 1,
"unit_amount": "1200.00",
"tax_amount": 0,
"metadata": {
"custom_field_1": "custom data 1",
"custom_field_2": "custom data 2",
},
}
]
},
// either pass the customer_id or the customer object
"customer_id": "cus_abc123...",
// create a new customer
"customer": {
"reference": "CLN240919000001",
"company_name": null,
"person_name": "John",
"person_surname": "Doe",
"client_type_lookups_id": "loo_abc123...",
"id_type_lookups_id": "loo_abc123...",
"id_number": "900112....",
"email": "johndoe@mail.com",
"contact_number": "+27831234567",
"billing_address": {
"line1": "1 Loop Street",
"line2": "Floor 5",
"city_or_town": "Cape Town",
"province_or_state": "Western Cape",
"postal_or_zip_code": "8001",
"country_lookups_id": "loo_abc123..."
},
"shipping": {
"contact_name": "Jane Doe",
"contact_number": "+27820000000",
"address": {
"line1": "1 Loop Street",
"line2": "Floor 5",
"city_or_town": "Cape Town",
"province_or_state": "Western Cape",
"postal_or_zip_code": "8001",
"country_lookups_id": "loo_abc123..."
},
},
"metadata": {
"custom_field_1": "custom data 1",
"custom_field_2": "custom data 2",
},
},
"redirects": {
"success_url": "https://merchant.example/success?order=ord_12345",
"cancel_url": "https://merchant.example/cancel?order=ord_12345",
"notify_url": "https://merchant.example/webhooks/payments"
},
"payment": {
"payment_methods_ids": ["pam_abc123"],
"metadata": {
"custom_field_1": "custom data 1",
"custom_field_2": "custom data 2",
},
},
"card": {
"request_3ds": "automatic", // always
"save_card": true,
"payment_type": "DB", // PA
},
"notifications": {
"send_invoice": true,
"send_confirmation_email": true,
"confirmation_email_override": "accounts@example.com"
},
"customization": {
"locale": "en-ZA",
"theme": "light",
"type": "page", // or embed
"display_cancel_button": true,
"display_total": true,
"display_cart": true,
"brand": {
"primary": "#00DC82",
}
},
}
Request Parameters
Field | Required | Type | Description | Example |
|---|---|---|---|---|
| mode | Y | String | Payment mode - one-off, recurring, or save | one-off |
| amount | Y | String | Payment amount | 1200.00 |
| currency | Y | String | Currency code | ZAR |
| order_id | C | String(32) | Either pass order_id OR order object. ID of existing order | ord_12345 |
| order.reference | C | String(35) | Order reference identifier | ORD0045 |
| order.description | C | String | Description of the order | Monthly plan + setup |
| order.items.sku | C | String | Product SKU | plan_pro_monthly |
| order.items.name | C | String | Product name | Pro Plan (Monthly) |
| order.items.quantity | C | Integer | Item quantity | 1 |
| order.items.unit_amount | C | String | Unit price | 1200.00 |
| order.items.tax_amount | N | Number | Tax amount | 0 |
| customer_id | C | String(32) | Either pass customer_id OR customer object. ID of existing customer | cus_abc123... |
| customer.reference | C | String(35) | Reference to identify a specific customer | CLN240919000001 |
| customer.company_name | N | String(64) | Company name if applicable | null |
| customer.person_name | C | String(32) | Customer's first name | John |
| customer.person_surname | C | String(32) | Customer's surname | Doe |
| customer.client_type_lookups_id | C | String(32) | Client type lookup ID | loo_abc123... |
| customer.id_type_lookups_id | C | String(32) | ID type lookup (e.g. South African ID, passport) | loo_abc123... |
| customer.id_number | C | String(13) | ID number | 900112... |
| customer.email | C | String(128) | Customer email address | johndoe@mail.com |
| customer.contact_number | C | String(16) | Customer contact number | +27831234567 |
| customer.billing_address.line1 | Y | String | Billing address line 1 | 1 Loop Street |
| customer.billing_address.city_or_town | Y | String | Billing city | Cape Town |
| customer.billing_address.postal_or_zip_code | Y | String | Postal code | 8001 |
| customer.billing_address.country_lookups_id | Y | String(32) | Country lookup ID | loo_abc123... |
| redirects.success_url | Y | String | URL to redirect on successful payment | https://merchant.example/success |
| redirects.cancel_url | Y | String | URL to redirect on cancelled payment | https://merchant.example/cancel |
| redirects.notify_url | Y | String | Webhook URL for payment notifications | https://merchant.example/webhooks/payments |
| payment.payment_methods_ids | Y | Array | Array of allowed payment method IDs | "pam_abc123" |
| card.request_3ds | N | String | 3D Secure request mode (automatic/always) | automatic |
| card.save_card | N | Boolean | Whether to save the card for future use | true |
| card.payment_type | N | String | Payment type (DB for debit, PA for preauth) | DB |
| notifications.send_invoice | N | Boolean | Whether to send invoice | true |
| notifications.send_confirmation_email | N | Boolean | Whether to send confirmation email | true |
| customization.locale | N | String | UI locale | en-ZA |
| customization.theme | N | String | UI theme | light |
| customization.type | N | String | UI type - page or embed | page |
| customization.display_cancel_button | N | Boolean | Whether to display the cancel button | true |
| customization.display_total | N | Boolean | Whether to display the total amount | true |
| customization.display_cart | N | Boolean | Whether to display the cart/order items | true |
| customization.brand.primary | N | String | Primary brand color in hex format | #00DC82 |
Response Body
{
"status": true,
"result": {
"id": "chk_abc123...",
"session_id": "ses_abc123...",
"amount": "1200.00",
"currency": "ZAR",
"order_id": "ord_12345",
"customer_id": "cus_abc123...",
"page_url": "https://checkout.kwik.co.za/pay/cs_test_a1b2c3",
"expires_at": "2025-09-13T12:30:00Z",
}
}
Response Parameters
Field | Type | Description | Example |
|---|---|---|---|
| status | Boolean | Indicates if the request was successful | true |
| result.id | String | Unique checkout session identifier | chk_abc123... |
| result.session_id | String | Session identifier for the checkout | ses_abc123... |
| result.amount | String | Checkout amount | 1200.00 |
| result.currency | String | Currency code | ZAR |
| result.order_id | String(32) | Associated order ID | ord_12345 |
| result.customer_id | String(32) | Associated customer ID | cus_abc123... |
| result.page_url | String | URL to redirect user to complete checkout | https://checkout.kwik.co.za/pay/cs_test_a1b2c3 |
| result.expires_at | String | ISO timestamp when the checkout session expires | 2025-09-13T12:30:00Z |
Webhook
When a checkout session is completed, updated, or expires, a webhook notification is sent to the notify_url specified in the request.
Webhook Payload
{
"event": "checkout.completed", // checkout.expired, checkout.failed
"data": [{
"checkout": {
"id": "chk_abc123...",
"session_id": "ses_abc123...",
"amount": "1200.00",
"currency": "ZAR",
"order_id": "ord_12345",
"customer_id": "cus_abc123...",
// return a card token if storing card details
"card": {
"token": "60d678e2465b5b6c4fd5e847ef39c70c4b0c22d1b826f39eb80a107b3b8433ad",
},
"transaction_id": "tra_abc123...",
"transaction_status_lookups_id": "loo_abc123",
"expires_at": "2025-09-13T12:30:00Z",
"completed_at": "2025-09-13T10:15:30Z"
},
"payment": {
"id": "pay_abc123...",
"amount": "1200.00",
"currency": "ZAR",
"status": "paid",
"payment_method": "card",
"created_at": "2025-09-13T10:15:30Z"
}
}],
"created_at": "2025-09-13T10:15:30Z"
}
Webhook Payload Parameters
Field | Type | Description | Example |
|---|---|---|---|
| event | String | Type of webhook event that occurred | checkout.completed |
| data | Array | Array containing checkout and payment data | ... |
| data.checkout.id | String | Unique checkout session identifier | chk_abc123... |
| data.checkout.session_id | String | Session identifier for the checkout | ses_abc123... |
| data.checkout.amount | String | Checkout amount | 1200.00 |
| data.checkout.currency | String | Currency code | ZAR |
| data.checkout.order_id | String(32) | Associated order ID | ord_12345 |
| data.checkout.customer_id | String(32) | Associated customer ID | cus_abc123... |
| data.checkout.card.token | String | Card token if card was saved | 60d678e2465b5b6c4fd5e847ef39c70c4b0c22d1b826f39eb80a107b3b8433ad |
| data.checkout.transaction_id | String | Transaction identifier | tra_abc123... |
| data.checkout.transaction_status_lookups_id | String | Transaction status lookup ID | loo_abc123 |
| data.checkout.expires_at | String | ISO timestamp when checkout session expires | 2025-09-13T12:30:00Z |
| data.checkout.completed_at | String | ISO timestamp when checkout was completed | 2025-09-13T10:15:30Z |
| data.payment.id | String | Payment identifier | pay_abc123... |
| data.payment.amount | String | Payment amount | 1200.00 |
| data.payment.currency | String | Payment currency | ZAR |
| data.payment.status | String | Payment status | paid |
| data.payment.payment_method | String | Payment method used | card |
| data.payment.created_at | String | ISO timestamp when payment was created | 2025-09-13T10:15:30Z |
| created_at | String | ISO timestamp when webhook was created | 2025-09-13T10:15:30Z |
Webhook Events
| Event | Description | Trigger Condition | Data Included |
|---|---|---|---|
checkout.completed | Checkout session was successfully completed with payment | When customer completes payment successfully | Checkout details, payment information, transaction data |
checkout.expired | Checkout session expired without completion | When checkout session reaches expiry time without payment | Checkout details only, no payment data |
checkout.failed | Checkout session failed due to payment failure | When payment processing fails (declined card, insufficient funds, etc.) | Checkout details, failed payment attempt, error information |
checkout.abandoned | Customer abandoned the checkout process | When customer leaves checkout page without completing | Checkout details, abandonment timestamp |
checkout.pending | Payment is pending additional verification | When payment requires manual review or 3DS authentication | Checkout details, pending payment status |
checkout.cancelled | Checkout was cancelled by customer or system | When cancel button is used or system cancels due to fraud | Checkout details, cancellation reason |
Webhook Security
All webhooks are sent with the following headers for verification:
X-Signature: HMAC-SHA256 signature of the payloadX-Timestamp: Unix timestamp of when the webhook was sentUser-Agent:Kwik-Webhooks/1.0
Webhook Response
Your endpoint should respond with a 200 status code to acknowledge receipt. Failed webhooks will be retried up to 3 times with exponential backoff.
Mandates
Create and manage payment mandates for recurring transactions including DebiCheck and Registered Mandates. Handle mandate creation, authentication, status updates, and cancellation with full SARB compliance.
Payment 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.