How to connect Kaspi Pay to WooCommerce with KZ Pay
A practical setup guide for teams preparing a WooCommerce store for Kaspi Public QR API Scheme 1 payments through KZ Pay.
- Merchant setup
- WooCommerce gateway
- Checkout validation
Confirm the environment first
Most payment problems are caused by missing merchant credentials, unsupported currency or an incomplete Kaspi device setup.
Pre-flight checklist
- WooCommerce is active and configured for KZT.
- The production website uses HTTPS.
- The server runs PHP 8.1 or newer with OpenSSL.
- The merchant has access to Kaspi Public QR API Scheme 1.
- The store owner has the production Kaspi API key and trade point details.
No webhook step is required
KZ Pay does not expose a webhook setup flow. Payment status is synchronized by server-side polling and local recovery logic.
Connect WooCommerce and Kaspi Pay in controlled steps
Use the plugin settings as the source of truth. The checkout method should only be enabled when readiness checks pass.
-
1
Install and activate KZ Pay
Install the WooCommerce payment plugin, complete the Freemius license or trial flow, and confirm WooCommerce is running on the target store.
-
2
Add the Kaspi production API key
Open the payment settings, enter the production API key and run the connection check from the admin screen.
-
3
Load trade points
Fetch available Kaspi trade points and choose the trade point that should receive checkout payments.
-
4
Register the payment device
Register the generated WooCommerce device with Kaspi. The device token is stored encrypted by the plugin.
-
5
Enable the payment method
Enable the WooCommerce gateway only after the plugin reports that checkout readiness is complete.
-
6
Place a controlled test order
Use a KZT order and confirm that the buyer reaches the KZ Pay payment page, authorizes through Kaspi and returns to WooCommerce.
Understand what store staff will see
The payment page and order metadata separate active payment attempts, temporary failures and cases that need manual review.
Pending and active
The buyer is choosing or authorizing payment. The plugin keeps polling while the provider status remains non-terminal.
Paid
WooCommerce payment completion is triggered only after Kaspi returns Processed with a valid transaction and matching amount.
Manual review
Amount mismatch, missing transaction data or uncertain local completion can put the order into a review state instead of silently completing it.
Expired or failed
Expired QR tokens, user cancellation, provider failures and insufficient funds are treated as terminal failed flows that can be retried by the customer.
Common setup checks
Use these checks before escalating to technical support.
Gateway does not appear at checkout
- Confirm WooCommerce currency is KZT.
- Confirm the gateway is enabled.
- Confirm API key, trade point and device registration are ready.
- Confirm the Freemius license or trial is active for the premium runtime.
Payment stays pending
- Check whether the status API version was detected.
- Confirm WordPress cron or Action Scheduler is running.
- Review WooCommerce order notes for the provider status.
- Use the support reference when contacting support.
Customer cannot pay
- Check QR expiration timing.
- Ask mobile users to use the payment link flow.
- Confirm the order total is greater than zero.
- Confirm the buyer is using a supported Kaspi Pay account.
KZ Pay is independently developed by Group Starlight and is not affiliated with, endorsed by, sponsored by, or an official product of Kaspi.kz. Kaspi and related trademarks belong to their respective owners.
Need the product page before implementation?
Keep the product landing page connected to this guide so buyers and technical teams see the same requirements.
Support: support@group-starlight.com