# Click Integration

> 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.

- Skill: `ubranch/click-integration` (Agent Skill, multi-file: 16 files)
- Install (CLI): `npx skillmds@latest add ubranch/click-integration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ubranch/click-integration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Finance & Business
- Author: ubranch (https://skillmd.com/u/ubranch)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/ubranch/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

| 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