How to Connect Kaspi Pay to WooCommerce | KZ Pay

Before you start

What you need before connecting Kaspi Pay

Start with merchant access and store readiness. Most failed setups come from missing Kaspi Pay credentials, the wrong store currency or an unregistered store.

Setup checklist

WooCommerce is installed and active.
The store currency is set to KZT.
The production website uses HTTPS.
The merchant has Kaspi Pay access for online payments.
A Kaspi Pay API key is available.
At least one Kaspi trade point is available for checkout payments.

Setup path

Connect Kaspi Pay to WooCommerce step by step

The exact screen labels depend on the plugin you use, but a reliable setup always follows the same path: credentials, trade point, store registration, checkout enablement and testing.

1

Confirm WooCommerce basics

Make sure WooCommerce is active, the store currency is KZT and checkout works before adding a Kaspi payment method.
2

Install the WooCommerce integration

Install and activate the payment plugin, then complete any license or trial activation required by the plugin.
3

Add the Kaspi Pay API key

Open the plugin settings, save the production Kaspi Pay API key and run the connection test from WordPress.
4

Select the trade point

Load the merchant trade points from Kaspi and choose the trade point that should receive WooCommerce checkout payments.
5

Register the store

Complete store registration from the plugin settings so the WooCommerce website can create Kaspi payments.
6

Enable checkout

Turn on the WooCommerce payment method only after the API key, trade point and store registration are ready.
7

Test desktop QR payments

Place a controlled KZT test order on desktop, scan the Kaspi QR and confirm the WooCommerce order updates after the final payment result.
8

Test mobile payment links

Place a controlled mobile test order and confirm that the payment link opens Kaspi correctly on the same device.

Payment flow

What happens after the customer chooses Kaspi Pay

A good WooCommerce integration keeps customer payment, payment status and order update logic separate.

Desktop Kaspi QR

Desktop customers see a Kaspi QR code on the payment page and scan it with the Kaspi app on another device.

Mobile payment link

Mobile customers should receive a payment link so they can continue in Kaspi on the same device.

Payment status tracking

The integration should keep checking payment status until Kaspi returns a final paid, failed, cancelled or expired result.

WooCommerce order update

WooCommerce should update the order only after the final payment result is received and matched to the order amount.

Testing before launch

Test paid, failed, expired and abandoned payment attempts before enabling the method for real customers.

Refund workflow

Automatic API refunds are not available with the current Kaspi QR integration. Process the monetary refund in the Kaspi Pay app first, then record the refund in WooCommerce.

Troubleshooting

Troubleshooting real merchant issues

Use these checks before escalating to technical support or changing checkout logic.

Payment method not visible

Confirm the store currency is KZT.
Confirm the WooCommerce payment method is enabled.
Confirm the API key, trade point and store registration are ready.
Confirm the plugin license or trial is active if the integration requires one.

Connection test fails

Confirm the Kaspi Pay API key is copied without extra spaces.
Make sure the key belongs to the production merchant account used for the store.
Confirm the server can make outbound HTTPS requests.
Check whether security plugins or hosting firewall rules are blocking the request.

Trade points do not load

Confirm the API key has access to the expected merchant trade points.
Re-run the connection test before loading trade points.
Ask the merchant to confirm that the trade point is active in Kaspi Pay.
Check WordPress admin notices and order logs for the returned error.

Store registration fails

Confirm the production website URL uses HTTPS.
Confirm the selected trade point is correct.
Save the API key and trade point again, then retry store registration.
If the same error repeats, contact support with the exact admin error and website URL.

Kaspi QR cannot be created

Confirm the order total is greater than zero and in KZT.
Confirm checkout readiness is complete.
Check whether the selected trade point can accept this payment type.
Review the WooCommerce order notes for the payment attempt error.

Payment remains pending

Do not mark the order paid manually unless the merchant verifies the payment in Kaspi.
Confirm WordPress cron or Action Scheduler is running.
Refresh the WooCommerce order notes to see the latest payment status.
Contact support with the order number and payment reference if the final result is not received.

Customer paid but order did not update

First verify the monetary payment in the Kaspi Pay app.
Confirm the paid amount matches the WooCommerce order total.
Check the order notes for a delayed, failed or manual-review status.
If the payment is real, record the operational decision in WooCommerce before fulfillment.

Mobile payment link does not open

Test from a real mobile browser, not only an embedded preview.
Confirm the payment link was created for the same order attempt.
Ask the customer to update or open the Kaspi app manually if the browser cannot deep-link.
Offer desktop Kaspi QR as an alternative when possible.

Payment expired

Ask the customer to start a new payment attempt from WooCommerce.
Do not reuse an expired QR code or payment link.
Confirm the old attempt remains visible in order notes.
If expiration happens too quickly, review the merchant setup and support logs.

FAQ

Common questions before connecting Kaspi Pay

Short answers for store owners and support teams. Use the dedicated QR guide for deeper QR-specific behavior.

Do I need a Kaspi Pay account before connecting WooCommerce?

Yes. WooCommerce integration requires merchant-side Kaspi Pay access, a Kaspi Pay API key and an active trade point.

Can WooCommerce mark the order paid when a QR code appears?

No. Creating a Kaspi QR or payment link only starts the payment attempt. WooCommerce should update the order after the final payment result is received.

What is a trade point?

A trade point is the merchant location or sales point in Kaspi Pay that receives the payment for WooCommerce checkout orders.

Do mobile customers scan a QR code on the same phone?

Usually no. Mobile customers should use a payment link that opens Kaspi on the same device. Desktop customers can scan a Kaspi QR from another device.

How should I test before going live?

Place controlled KZT orders and check successful payment, cancellation, expiration, abandoned checkout and mobile payment link behavior.

Are automatic refunds supported?

Automatic API refunds are not available with the current Kaspi QR integration. Process the monetary refund in the Kaspi Pay app first, then record the refund in WooCommerce.

Where can I read more about Kaspi QR behavior?

Use the dedicated Kaspi QR guide for QR-specific payment flow details.

WooCommerce plugin option

A Ready-Made WooCommerce Integration

KZ Pay provides a maintained WooCommerce integration for Kaspi QR payments and payment links, including merchant setup, payment-status tracking and WooCommerce order updates.

7-day free trial. No credit card required.

Explore KZ Pay Read KZ Pay Documentation

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.