Click Integration

Click Payment Integration — Expert Guide

This skill makes you a super-expert on Click payment system integration in Uzbekistan. Every page from docs.click.uz is captured in the reference files below — nothing is cut or summarized.

Quick Reference

Choosing the Right Integration Method

Click offers multiple ways to accept payments. Read the appropriate reference file for full details.

1. SHOP API — "Click calls YOUR server" (most common)

• User pays via Click → Click sends Prepare/Complete to your server
• You implement 1 callback endpoint handling 2 actions
• Read: references/02-shop-api-requests.md

2. Payment Button/Link — "Redirect user to Click"

• Simple link/form redirects user to my.click.uz payment page
• Works with SHOP API callback on your server
• Read: references/05-payment-button.md

3. Inline Checkout — "Pay on YOUR site without redirect"

• Embed checkout.js widget — payment form opens as overlay
• No redirect to my.click.uz needed
• Read: references/06-inline-checkout.md

4. Merchant API — "YOU call Click's server"

• Create invoices, check payment status, refund, card tokens
• Supplements SHOP API, not a replacement
• Read: references/08-merchant-api-requests.md

5. CLICK Pass — "QR-code POS payment"

• Merchant scans QR from user's Click app
• For physical retail, kiosks
• Read: references/10-click-pass.md

6. Telegram Bot Payments

• Accept payments inside Telegram via Click provider
• Uses Telegram Bot API with Click provider_token
• Read: references/12-telegram-payments.md

7. Mobile SDK / Deep Links

• Android SDK library or deep link integration (Android + iOS)
• Read: references/13-mobile-sdk.md

Decision Matrix

Sign String Formulas (SHOP API)

CRITICAL: Parameters concatenated WITHOUT separators. Use constant-time comparison (e.g., crypto.timingSafeEqual).

Merchant API Authentication

Auth: {merchant_user_id}:{digest}:{timestamp}

• digest = SHA1(timestamp + secret_key)
• timestamp = UNIX timestamp (10-digit seconds)

Error Codes Summary (SHOP API)

Merchant API HTTP Error Codes

Before You Start — Setup Checklist

1. Register with Click and sign contract with connected bank
2. Receive credentials: merchant_id, service_id, SECRET_KEY, merchant_user_id
3. Get access to merchant cabinet at merchant.click.uz
4. Set Prepare URL and Complete URL in merchant cabinet → Сервисы → pencil icon
5. Request service activation from Click support (disabled by default!)
6. If NOT on TAS-IX: provide domain + IP + port for firewall whitelisting
7. Static IP required — notify Click before changing

Critical Implementation Rules

1. Single callback endpoint — one URL for both Prepare (action=0) and Complete (action=1)
2. Content-Type is form-urlencoded — SHOP API sends application/x-www-form-urlencoded, NOT JSON
3. Amounts in SO'M — NOT tiyin! Float format: 50000.00
4. Always verify sign_string with constant-time comparison
5. Check error field in requests — if Click sends error ≤ -1, respond with error -9
6. Protect against duplicate click_trans_id processing
7. Verify merchant_prepare_id in Complete matches Prepare record
8. Complete error=0 → fulfill order; error<0 → cancel order
9. Fiscalization mandatory for more than 1 IKPU code
10. Service must be activated by Click support before real payments
11. IP must be static — notify Click before any change
12. Log click_paydoc_id — shown in user's SMS, needed for support queries

Common Gotchas

• Callback URLs must be publicly accessible — localhost won't work in production
• Prepare URL validation — merchant cabinet validates format; must be valid HTTPS URL
• sign_string concatenation — NO separators between params
• merchant_prepare_id overflow — use proper integer, Date.now() % 2147483647 causes collisions
• Response must always be JSON with all required fields, even on error
• After successful Complete (error=0) — response CANNOT be error (except -4 or -9)
• If fulfillment fails after successful Complete — respond success, then cancel via Merchant API reversal

Reference Files — Complete docs.click.uz Mirror

Each file corresponds 1:1 to a docs.click.uz page. Nothing is cut.

SHOP API

• references/01-shop-api-overview.md — General provisions, terms, flow diagram
• references/02-shop-api-requests.md — Prepare & Complete full spec with code examples
• references/03-shop-api-errors.md — All error codes (Click-side and merchant-side)
• references/04-shop-api-testing.md — Testing software, scenarios, report generation

Payment Integration

• references/05-payment-button.md — Payment link URL and HTML form (with redirect)
• references/06-inline-checkout.md — checkout.js widget, createPaymentRequest() JS API

Merchant API

• references/07-merchant-api-overview.md — General provisions, terms, flow diagram, contract info
• references/08-merchant-api-requests.md — All endpoints: invoice, payment status, reversal, card token
• references/09-merchant-api-errors.md — HTTP status codes

Additional

• references/10-click-pass.md — QR-code POS payments, confirm mode
• references/11-fiscalization.md — OFD submit_items, submit_qrcode, get fiscal data
• references/12-telegram-payments.md — Bot setup, sendInvoice, pre_checkout_query, live mode
• references/13-mobile-sdk.md — Android SDK, iOS deep links, return_url handling
• references/14-server-examples.md — Official PHP, Django repos + community Node.js/TypeScript
• references/15-cms-plugins.md — WooCommerce, OpenCart, Drupal, 1C-Bitrix, Joomla, CS-Cart