KZ Pay Documentation
Learn how to install, connect and configure KZ Pay for WooCommerce, from license activation and Kaspi Pay setup to checkout testing and troubleshooting.
- Getting started
- Kaspi Pay connection
- Checkout testing
Configure KZ Pay in the right order
Start with requirements, then install, activate, connect Kaspi Pay, register this store and enable checkout only after readiness is complete.
Before installation
Confirm WordPress, WooCommerce, HTTPS, KZT currency, Kaspi Pay access, a Kaspi Pay API key and a trade point before enabling checkout.
Install and activate
Upload the KZ Pay ZIP, activate it in WordPress and complete the Freemius license or trial flow.
Connect Kaspi Pay
Save the Kaspi Pay API key, test the connection, load trade points, select one and register this store.
Enable checkout
Enable KZ Pay only after the API key, trade point and store registration are ready.
Payments and orders
Customers pay through a QR code or mobile payment link. KZ Pay tracks the result and updates the matching WooCommerce order.
Troubleshooting and support
Use issue-based checks first, then contact support without sending credentials or full sensitive logs.
Getting Started
Before installing KZ Pay, make sure your WordPress store and Kaspi Pay account meet the required conditions.
- WordPress 6.9 or newer is available
- WooCommerce 7.0 or newer is installed and active
- The production site uses HTTPS
- WooCommerce store currency is KZT
- The merchant has Kaspi Pay access
- The merchant has a Kaspi Pay API key
- At least one Kaspi Pay trade point is configured
- The server runs PHP 8.1 or newer with OpenSSL
Kaspi Pay access is separate
KZ Pay does not provide a Kaspi Pay account or API key. These must be obtained separately by the merchant through Kaspi Pay.
Installation
Install KZ Pay like a standard commercial WordPress plugin ZIP, then open its settings before enabling checkout.
- Download the ZIP package Use the installable KZ Pay ZIP package from your purchase or download area.
- Upload in WordPress In WordPress, go to Plugins > Add New > Upload Plugin.
- Install and activate Upload the ZIP file, install it and activate the plugin.
- Open KZ Pay settings Use the Kaspi Pay admin menu or WooCommerce > Settings > Payments > KZ Pay for WooCommerce.
License Activation
After activation, complete the Freemius license or trial flow in WordPress. Product downloads, updates, license-managed access and technical support depend on an active trial or subscription.
- Start activation Follow the Freemius prompt shown after plugin activation.
- Enter license details Use the purchase email or license key from the KZ Pay customer account.
- Confirm active status Confirm that Freemius shows an active trial or subscription before relying on downloads, updates or support access.
- If activation fails Check the purchase email, license status and WordPress connectivity to Freemius, then try again.
Kaspi QR Connection
The KZ Pay settings screen uses the same customer-facing labels shown below. Complete these steps before checkout is enabled.
Kaspi Pay API key and setup steps
The Kaspi Pay API key lets KZ Pay connect your WooCommerce store to Kaspi Pay from the WordPress server. Do not paste real credentials into support messages, screenshots or public documentation.
- Enter Kaspi Pay API key Open Kaspi QR Connection and paste the production API key issued to your organization.
- Save API key Click Save API key. The saved key is encrypted and is not displayed again.
- Test connection Click Test connection before loading trade points.
- Load trade points Click Load trade points to fetch available Kaspi Pay trade points.
- Select Trade point Choose the Trade point that should receive payments from this WooCommerce store.
- Register this store Click Register this store. KZ Pay sends the generated KZ Pay Device ID and selected trade point to Kaspi Pay.
- Enable checkout After the readiness list is complete, enable KZ Pay at WooCommerce checkout and save.
Trade Point & Store Registration
A trade point is the Kaspi Pay location or point that should receive payments from this WooCommerce store. Store registration links this WordPress installation to the selected trade point.
Trade point
Select the Kaspi Pay trade point that should receive checkout payments.
KZ Pay Device ID
Generated automatically for this WordPress installation and shown in the settings screen.
Store registration
The settings screen shows Registered with Kaspi Pay after successful registration.
Disconnect this store
Use this only when the store should be unregistered or moved; checkout is disabled after disconnecting.
Checkout Setup
Enable KZ Pay at checkout only after the connection and registration steps are complete.
- Kaspi Pay API key saved
- Trade point selected
- Store registered with Kaspi Pay
- Enable KZ Pay at WooCommerce checkout is checked
- Checkout and order currency is KZT
Before Accepting Live Payments
Use a controlled real checkout before relying on KZ Pay for customer payments. Confirm that the QR or payment-link flow completes and that the matching WooCommerce order receives the final payment result.
- API key configured
- Correct trade point selected
- Store registered
- KZ Pay enabled at checkout
- Checkout currency is KZT
- One controlled payment completed
- WooCommerce receives the final result
- The order updates correctly
How KZ Pay handles payments
After WooCommerce creates an order, KZ Pay sends the customer to a protected payment page and creates either a Kaspi QR request or a mobile payment link.
Kaspi QR Payments
- Customer places an order WooCommerce creates the order and redirects the customer to the KZ Pay payment page.
- KZ Pay creates a payment request The plugin sends the order amount and generated payment reference to Kaspi Pay.
- Customer confirms payment Desktop customers scan the QR code in Kaspi. Mobile customers can continue through the Kaspi app link.
- KZ Pay tracks the result The plugin checks the payment status from the WordPress server.
- WooCommerce updates the order WooCommerce is updated only after a final payment result is received and validated.
Mobile Payment Links
For mobile checkout, KZ Pay can provide a payment link so the customer can continue the payment flow in Kaspi on the same device instead of scanning the same screen.
Payment Status & WooCommerce Orders
KZ Pay tracks the payment status and updates the corresponding WooCommerce order after a final payment result is received.
Waiting for payment
The customer is viewing the QR code or payment link and Kaspi has not returned a final result.
Payment completed
Kaspi returns a processed result with valid transaction data and a matching amount.
Payment failed or expired
Kaspi returns a terminal failure, cancellation or expiration state. The customer can retry when the stored state allows it.
Manual review
KZ Pay cannot safely complete or fail the order automatically and records that administrator review is needed.
Refunds
Automatic API refunds are not available with the current Kaspi QR integration. Process the refund in the Kaspi Pay app first, then record it in WooCommerce. Recording a refund in WooCommerce is not necessarily the same operation as returning money through Kaspi Pay.
Common setup checks
Use these checks before escalating to technical support. Never include API keys, passwords or full sensitive logs in a support message.
KZ Pay does not appear at checkout
- Possible cause
- The gateway is disabled, setup is incomplete, the currency is not KZT, or license status needs review.
- What to check
- Check the readiness list in Checkout Setup, confirm the order currency is KZT and review the Freemius license or trial status.
- What to do next
- Complete API key, trade point and store registration, then enable and save checkout settings.
Connection test fails
- Possible cause
- The API key is missing, invalid or cannot reach Kaspi Pay from the server.
- What to check
- Confirm the production API key was copied correctly and the server can make outbound HTTPS requests.
- What to do next
- Save the key again and run Test connection. If it still fails, contact support without sending the key.
Trade points do not load
- Possible cause
- Kaspi Pay returned no trade points or the API key does not have access to them.
- What to check
- Confirm the merchant has configured trade points in Kaspi Pay.
- What to do next
- Use Load trade points again after Kaspi Pay setup is corrected.
Store registration fails
- Possible cause
- No trade point is selected or Kaspi Pay rejected registration for this store.
- What to check
- Select the correct Trade point and confirm the API key belongs to that organization.
- What to do next
- Click Register this store again or contact support with the request reference if available.
QR payment cannot be created
- Possible cause
- Checkout is not ready, GD/PNG support is missing or Kaspi rejected the payment request.
- What to check
- Check KZT currency, readiness status, server PHP extensions and WooCommerce order total.
- What to do next
- Correct the issue and retry the order. Use another payment method if the customer is waiting.
Payment remains pending
- Possible cause
- Kaspi has not returned a final result or WordPress scheduled actions are delayed.
- What to check
- Check WooCommerce order notes and make sure WordPress cron or Action Scheduler is running.
- What to do next
- Wait for the next status check or contact support with the WooCommerce order ID.
Customer completed payment but WooCommerce did not update
- Possible cause
- KZ Pay could not safely validate the final result or local completion needs review.
- What to check
- Check the WooCommerce order notes for manual review, amount mismatch or missing transaction data.
- What to do next
- Do not create duplicate payments. Contact support with the order ID and safe log excerpt.
Payment link does not open
- Possible cause
- The customer is using an unsupported browser/app path or the returned link is no longer active.
- What to check
- Ask the customer to retry checkout and confirm they can open Kaspi on the device.
- What to do next
- Retry the payment when the previous attempt is terminal or use another payment method.
Payment expired
- Possible cause
- The QR code or payment link was not confirmed before the provider timeout.
- What to check
- Confirm whether the WooCommerce order shows failed, expired or retry state.
- What to do next
- Let the customer retry only when KZ Pay shows that retry is allowed.
License activation fails
- Possible cause
- The license is inactive, entered with the wrong email or Freemius cannot validate it.
- What to check
- Check the KZ Pay customer account, purchase email and subscription status.
- What to do next
- Renew or activate the license, then reload the KZ Pay settings page.
KZ Pay documentation FAQ
Short answers to common setup and support questions.
Where do I enter my Kaspi Pay API key?
Open the Kaspi Pay admin menu or WooCommerce > Settings > Payments > KZ Pay for WooCommerce, then use the Kaspi QR Connection section.
How do I select a trade point?
Click Load trade points, then select the Trade point that should receive payments from this WooCommerce store.
Why does KZ Pay register my store?
Registration links this WordPress installation and its generated KZ Pay Device ID to the selected Kaspi Pay trade point.
Why is KZ Pay not visible at checkout?
Check whether setup is complete, the gateway is enabled, the checkout currency is KZT and the Freemius license or trial status is active.
How do customers pay on mobile?
Mobile customers can continue through a Kaspi payment link on the same device.
How does KZ Pay detect a successful payment?
KZ Pay checks the Kaspi payment status from the WordPress server and updates the matching WooCommerce order after a final valid result.
Can I use a currency other than KZT?
No. KZ Pay is available only for KZT checkout/orders.
How do refunds work?
Process the refund in the Kaspi Pay app first, then record it in WooCommerce. Automatic API refunds are not available with the current Kaspi QR integration.
Can I move KZ Pay to another WordPress installation?
A new WordPress installation receives its own KZ Pay Device ID and must be registered again with the correct trade point.
What information should I send to support?
Send your WordPress, WooCommerce and KZ Pay versions, the WooCommerce order ID and a safe description of the issue. Never send the Kaspi Pay API key.
Developer-level notes
These details help administrators and developers understand the implementation without making ordinary setup harder.
First Scheme (Simplified Access)
The current plugin is built for Kaspi Public QR API Scheme 1. Merchant setup does not require certificate flow configuration in WordPress.
API authorization model
KZ Pay sends the saved Kaspi Pay API key from the server side. The key is never printed in this public documentation.
DeviceToken
Kaspi Pay returns a DeviceToken during store registration. KZ Pay stores it for future payment requests.
Payment status polling
The plugin checks Kaspi payment status server side and stores the first working status API version when needed.
API status terminology
Common internal statuses include QrTokenCreated, RemotePaymentCreated, Wait, Processing, Processed and terminal failure states.
Supported API behavior
The current integration supports QR checkout, mobile payment links, device registration, trade point loading and server-side payment status tracking.
Need Help?
If you cannot resolve an issue using this documentation, contact KZ Pay Support at support@group-starlight.com. Include your WordPress, WooCommerce and KZ Pay versions together with the WooCommerce order ID related to the issue.
Never send your Kaspi Pay API key, passwords, full sensitive logs or credentials by email or support message.
Contact supportContinue with the right page
Use the product page for pricing and limits, or the guides when you need a broader implementation explanation.