click-integration: Скилл интеграции платежей Click

--- name: click-integration description: > Expert-level Click payment integration skill for Uzbekistan's Click SuperApp. Use whenever user mentions Click, click.uz, SHOP API, Merchant API, Click to'lov, Click integratsiya, Click callback, prepare/complete, click_trans_id, merchant_trans_id, Click fiscalization, Click button, Click invoice, card token, Click Pass, checkout.js, createPaymentRequest, Click Telegram, mobile SDK, merchant.click.uz, my.click.uz, api.click.uz, or Click error codes (-1 to -9). Covers SHOP API (Prepare/Complete), Merchant API (invoices, payments, tokens, reversal), payment button, inline checkout, CLICK Pass (QR POS), fiscalization (OFD/IKPU), Telegram bot payments, mobile SDK, CMS plugins (WooCommerce, OpenCart, 1C-Bitrix), testing, and deployment. Trigger for partial mentions like "click", "shop api", "click payment", "click pass", "click telegram", "click plugin" in Uzbek, Russian, or English. --- # 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 | Item | Value | |------|-------| | Payment page URL | `https://my.click.uz/services/pay` | | Merchant API endpoint | `https://api.click.uz/v2/merchant/` | | Merchant cabinet | `https://merchant.click.uz` | | Documentation | `https://docs.click.uz` | | SHOP API Protocol | HTTP/HTTPS POST, `application/x-www-form-urlencoded` | | Merchant API Protocol | HTTPS, `application/json` (also supports `application/xml`) | | Currency | UZS, amounts in **so'm** (NOT tiyin — unlike Payme!) | | Amount format | float with 2 decimal places (e.g., `1000.00`) | | SHOP API auth | MD5 sign_string hash | | Merchant API auth | SHA1 digest in `Auth` header | | Checkout.js CDN | `https://my.click.uz/pay/checkout.js` | | Android SDK | `https://github.com/click-llc/android-msdk` | ## 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 | Method | Who initiates | Where user pays | Best for | |--------|--------------|-----------------|----------| | SHOP API + Payment Button | User clicks link | Click web/app | E-commerce, web | | SHOP API + Inline Checkout | User on your site | Overlay on your site | SPA, custom UX | | Merchant API Invoice | Merchant sends invoice | User confirms in Click app | Subscriptions, push billing | | Merchant API Card Token | Merchant charges token | No user interaction | Recurring, card-on-file | | CLICK Pass | Merchant scans QR | Already in Click app | Physical retail, POS | | Telegram Payments | User in Telegram | Telegram payment UI | Telegram bots | | Mobile SDK / Deep Link | User in your app | Click app or browser | Mobile apps | ## Sign String Formulas (SHOP API) | Request | Formula | |---------|---------| | Prepare (action=0) | `MD5(click_trans_id + service_id + SECRET_KEY + merchant_trans_id + amount + action + sign_time)` | | Complete (action=1) | `MD5(click_trans_id + service_id + SECRET_KEY + merchant_trans_id + merchant_prepare_id + amount + action + sign_time)` | **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) | error | error_note | Description | |-------|------------|-------------| | 0 | Success | OK | | -1 | SIGN CHECK FAILED! | Signature verification failed | | -2 | Incorrect parameter amount | Wrong amount | | -3 | Action not found | Unknown action | | -4 | Already paid | Duplicate payment | | -5 | User does not exist | Order/user not found | | -6 | Transaction does not exist | Payment record not found | | -7 | Failed to update user | DB/balance update error | | -8 | Error in request from click | Malformed request | | -9 | Transaction cancelled | Previously cancelled | ## Merchant API HTTP Error Codes | Code | Description | |------|-------------| | 200, 201 | OK | | 400 | Bad request (malformed data or URI) | | 401 | Not authorized (auth error) | | 403 | Forbidden (method not allowed) | | 404 | Not found (method not found) | | 406 | Not acceptable (invalid data type) | | 410 | Gone (deprecated method) | | 500 | Internal server error | | 502 | Service is down or being upgraded | ## 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