Instructions for Payment via HUMO and UZCARD

What the add-on does

The add-on adds the “HUMO and UZCARD” payment processor to CS-Cart for accepting cards of Uzbekistan payment systems. Payments are sent to the QRPay JSON-RPC gateway: test mode uses http://testagent.qrpay.uz/api/jsonrpc, production mode uses https://agent.qrpay.uz/api/jsonrpc.

The payment flow is based on a hold. After SMS confirmation, the order amount is reserved on the customer card; the final capture is performed when the order is moved to the configured confirmation status.

Where to find the add-on

The mode setting is located in the add-on card: Add-ons → Manage add-ons → Payment via HUMO and UZCARD. The “General” section contains the Test Mode option.

Gateway credentials are configured in the payment method: Administration → Payment methods, processor HUMO and UZCARD. Use the “Gateway settings” block to enter terminal data and order statuses.

Add-on settings

Test Mode — when enabled, the add-on sends requests to the test gateway URL and writes additional request/response logs. When disabled, it uses the production QRPay URL.

Payment method settings

Login and Password — credentials used for Basic Auth when the add-on calls the gateway.

Terminal ID — terminal identifier issued by the payment provider.

Merchant number — merchant ID of the store in the payment system.

Terminal name and Port — technical terminal registration parameters. They are hidden in the interface and are filled with a random value by default if no saved value exists.

Paid order status — the status assigned to the order after successful SMS verification and hold creation.

Confirmed order status — the status that triggers capture from the hold.

Terminal status — terminal check result returned by the gateway. If the terminal is not registered, the add-on shows the registration button.

Terminal registration and check

After login, password, terminal ID, and merchant number are filled in, the add-on automatically checks the terminal with the terminal.check request. If the gateway confirms it, the status field shows “Registered”.

If the terminal is not found, the “Register” button becomes available. It sends terminal.add with terminal, merchant, port, and terminal name data.

Payment flow

The customer selects the HUMO and UZCARD payment method and enters card details. The add-on sends a card tokenization request and starts SMS verification.

After the SMS code is entered, the add-on verifies the code through the gateway. On success, it checks the card balance by token, compares it with the order total, and creates a hold for the order amount. The amount is sent in tiyin — the add-on multiplies the order total by 100.

If the hold is created successfully, the order receives the configured paid order status, and the hold ID is saved in the payment method parameters.

Capture confirmation

When the order is moved to the status selected in “Confirmed order status”, the add-on sends hold.dismiss.charge. After a successful response, the hold is removed from payment parameters and the funds are considered captured.

Refunds

If the payment has an active hold, the order page shows the “Return funds to the client” button. After confirmation, the add-on sends hold.dismiss, removes the hold from payment parameters, changes the order to the cancelled status, and adds a record to the order log.

The code does not implement a separate refund flow for already captured payments. The button works with an active hold before capture.

Webhook and callback

The add-on does not provide a configurable external webhook from the payment system. The callback is used inside CS-Cart for the SMS code page: the customer submits the code to a payment_notification.frame URL, and CS-Cart then completes order placement.

Receipts and fiscalization

The add-on code has no dedicated settings for fiscal receipts, 54-FZ, or DigitalKassa. If the store needs receipts, use a separate CS-Cart fiscalization integration and check the payment provider requirements.

Logs and diagnostics

On gateway errors, the add-on writes data to app/addons/ms_humo_uzcard/Tygh/Addons/MsHumoUzcard/logs/error_log.txt. In test mode, it also writes resp_req_log.txt with requests and responses.

If payment fails, check the mode, login, password, terminal ID, merchant number, terminal registration status, and the gateway response in the log.

How to check the result

Enable test mode, fill in the payment method credentials, and make sure the terminal status becomes “Registered”.

Create a test order and pay it with HUMO and UZCARD. Check that the SMS code form is displayed, the order receives the selected paid order status after a successful code entry, and the payment data stores the transaction/hold ID.

Move the order to the confirmation status and make sure the add-on captures the hold. To test cancellation, create another order with an active hold and use “Return funds to the client” before capture.