📄 specs/phase-06-click-payment.md📏 1039 qator💾 44.5 KB

Phase 06 — Click Payment Integration¶

Status: specification (implementation pending)
Depends on: Phase 02 (users/RBAC), Phase 03 (submissions + state machine + StatusHistory), Phase 05 (peer review — accepted transition triggers APC)
Cross-cutting: /root/projects/journal/specs/00-cross-cutting.md (all references below as "CC §…")

1. Maqsad & scope¶

1.1 Maqsad¶

Click Merchant API v2 orqali to'liq webhook tsiklini (prepare → complete → refund-callback) xavfsiz va idempotent implement qilish. Submission state machine bilan avtomatik integratsiya: Issue.payment_mode (upfront_on_submit / apc_after_accept / free) ga qarab kerakli momentda Invoice yaratish va payment_pending → paid transitioni. Uzbek BXM foizi asosida hisoblangan summa (yoki fiksirlangan so'm) saqlanadi. Bekor qilish va qaytarish (refund) — ikki pog'onali tasdiqlash bilan. Sandbox + production rejim toggle qilinadi adminpanel orqali.

1.2 Scope (ichida)¶

payments app ning asosiy qismi: Invoice, ClickTransaction, Refund, ClickSettings modellari
3 ta webhook endpoint: /api/click/prepare/, /api/click/complete/, /api/click/refund-callback/
2 ta user-facing page: pay page (Click redirect) va receipt page
Submission state integratsiyasi: submitted/accepted → payment_pending auto-trigger
BXM snapshot sistemasi: Issue.price_mode='bxm_percent' vaqtida joriy core.BxmSetting qiymatidan summa hisobi
PDF receipt auto-generator (reportlab)
Adminpanel: invoice list/filter, cancel, refund (approval workflow)
Celery refund retry chain
IP allowlist middleware (Click official IPs)
Audit log: har qanday moliyaviy amal

1.3 Scope (tashqari, boshqa fazalarga)¶

Payme, bank transfer — Phase 09
SMS invoice_created, invoice_paid shablonlari dispatch — Phase 10 (biroq bu faza signal yuboradi)
Muallif kabinetidagi "Mening to'lovlarim" list — Phase 02 dashboardga qo'shiladi; bu faza faqat backend API beradi
Financial hisobotlar — Phase 12
Legal entity (yuridik shaxs) invoice PDF — Phase 09

1.4 Kirish shartlari¶

Phase 05 ning submission_state_changed signali ishlayapti
Submission.payment_mode_snapshot to'g'ri to'ldirilgan (submit vaqtida Issue dan nusxa olingan)
core.BxmSetting modeli (joriy BXM qiymati) Phase 01 da o'rnatilgan
RBAC perms: invoice.view, invoice.create_manual, invoice.cancel, payment.refund_initiate, payment.refund_approve, settings.manage_click, settings.test_payment — seed qilinadi

1.5 Chiqish shartlari (exit criteria → §12)¶

Sandbox Click to'lovi muvaffaqiyatli tugagach, Submission.state avtomatik payment_pending → paid; sandbox refund sikli cancelled → refunded; barcha webhook idempotency va signature testlari o'tadi; PDF receipt generatsiya ishlaydi.

2. Bog'liqliklar¶

2.1 Ichki¶

Komponent	Nima uchun kerak
`submissions.state.transition()`	state o'zgartirish yagona entry point
`submissions.signals.submission_state_changed`	`submitted`/`accepted` → invoice yaratish trigger
`core.BxmSetting`	price_mode=bxm_percent vaqtida joriy BXM
`accounts.User` + RBAC	initiator/approver identity
`accounts.AuditLog`	invoice_cancel, refund_initiate, refund_approve yozish
`notifications.signals`	invoice_created, invoice_paid, refund_completed event emit
`adminpanel` base template	moliyaviy sahifa UI
`core.TimestampedModel`	created_at/updated_at

2.2 Tashqi¶

Tashqi xizmat	Qanday ishlatiladi	Sandbox
Click Merchant API v2	webhook-based payment flow	`my.click.uz` test kabinet
reportlab >= 4.0	PDF receipt va invoice	—
django-ratelimit	webhook rate limit	—
cryptography (Fernet)	`ClickSettings.secret_key` encrypted field	—

2.3 .env o'zgaruvchilari¶

# Production
CLICK_MERCHANT_ID=12345
CLICK_SERVICE_ID=67890
CLICK_SECRET_KEY=<hex_32>
CLICK_MERCHANT_USER_ID=54321
CLICK_ENDPOINT_URL=https://my.click.uz/services/pay
CLICK_IS_TEST=False
CLICK_ALLOWED_IPS=213.230.106.106,213.230.106.107,213.230.106.108

# Sandbox
CLICK_TEST_MERCHANT_ID=test_12345
CLICK_TEST_SERVICE_ID=test_67890
CLICK_TEST_SECRET_KEY=<hex_32>
CLICK_TEST_ENDPOINT_URL=https://my.click.uz/services/pay

Production qiymatlari ClickSettings singleton row (DB) orqali hot-reloadable — .env faqat dastlabki seed.

3. Funksional talablar¶

3.1 Invoice yaratish¶

FR-06-01: Submission submitted holatiga o'tgach, agar payment_mode_snapshot == 'upfront_on_submit' va plagiarism_check muvaffaqiyatli, desk_review dan keyin muharrir forward_to_payment qaroriga ko'ra Invoice yaratiladi; state desk_review → payment_pending.

FR-06-02: payment_mode_snapshot == 'apc_after_accept' va Submission accepted holatiga o'tgach, signal handler avtomatik Invoice yaratadi; state accepted → payment_pending.

FR-06-03: payment_mode_snapshot == 'free' — Invoice yaratilmaydi, state to'g'ridan-to'g'ri accepted → editing.

FR-06-04: Summa hisobi:
- Agar Issue.price_mode == 'fixed_soum': amount = Issue.price_fixed
- Agar Issue.price_mode == 'bxm_percent': amount = round(BxmSetting.get_current().amount * Issue.price_percent / 100, 2)
- Snapshotlar: bxm_snapshot, price_percent_snapshot, price_fixed_snapshot — hech qachon qayta hisoblanmaydi.

FR-06-05: Invoice.number format: INV-{year}-{6digit_seq} (masalan INV-2026-000123). Atomic counter core.SiteSetting key invoice_number_seq_2026 orqali select_for_update.

FR-06-06: Invoice.due_at = created_at + 10 kun default (configurable per Issue, keyingi fazada). 10 kun oxirida status=pending bo'lgan Invoice Celery beat orqali cancelled ga o'tadi.

FR-06-07: Invoice.external_order_id = number — Click merchant_trans_id sifatida ishlatiladi.

3.2 Pay page¶

FR-06-08: GET /payments/<invoice_no>/pay/click/ — Click hosted payment sahifasiga redirect. URL parametri:

https://my.click.uz/services/pay
  ?service_id={service_id}
  &merchant_id={merchant_id}
  &amount={amount}
  &transaction_param={invoice_no}
  &return_url={host}/payments/{invoice_no}/receipt/

Access: public (invoice_no bilan har kim ochishi mumkin, lekin hech qanday sensitive ma'lumot yo'q). Lekin Invoice.status != 'pending' bo'lsa 410 Gone.

3.3 Webhook: Prepare¶

FR-06-09: POST /api/click/prepare/ — Click server tomondan kelmoqda, action=0. Idempotency: (click_trans_id, action) unique. Signature tekshiriladi (§6.2). Invoice pending holatida bo'lishi shart, amount mos kelishi kerak.

Javob:

{
  "click_trans_id": "<num>",
  "merchant_trans_id": "INV-2026-000123",
  "merchant_prepare_id": "<invoice_id>",
  "error": 0,
  "error_note": "Success"
}

FR-06-10: Har Prepare muvaffaqiyatida ClickTransaction(action=0, is_valid_signature=true) yoziladi; Invoice.status o'zgarmaydi (hali pending).

3.4 Webhook: Complete¶

FR-06-11: POST /api/click/complete/ — action=1 (to'lov muvaffaqiyati) yoki action=-1 (Click bekor qildi, kam uchraydi).

FR-06-12: Signature va amount check ok bo'lsa:
- action=1: Invoice.status → 'paid', paid_at=now(), Submission.transition('payment_pending' → 'paid')
- action=-1 (merchant_prepare_id bilan): Invoice.status → 'cancelled', Submission payment_pending → cancelled

FR-06-13: Idempotency: ikkinchi marta bir xil (click_trans_id, action) kelsa, oldin saqlangan response qaytariladi (IntegrityError on unique → read existing response, 200).

FR-06-14: select_for_update Invoice satrida race condition himoyasi.

FR-06-15: PDF receipt avtomatik generatsiya qilinadi (Celery generate_receipt_pdf(invoice_id) task, queue q:default, soft=30s hard=60s). Fayl Invoice.pdf_receipt ga saqlanadi.

3.5 Webhook: Refund callback¶

FR-06-16: POST /api/click/refund-callback/ — Click gateway refund muvaffaqiyati/xatolari haqida xabar beradi (bizim so'rov bo'yicha). Signature tekshiriladi. Refund.status yangilanadi (succeeded / failed). Muvaffaqiyatda Invoice status='refunded' (to'liq) yoki partially_refunded.

3.6 Refund — initiate va approval¶

FR-06-17: Adminpanelda GET /admin-panel/invoices/<id>/refund/ forma: amount (to'liq / qisman), reason (majburiy text, ≥ 20 belgi), kind (full/partial). Perm: payment.refund_initiate (accountant, admin).

FR-06-18: POST → Refund(status='pending_approval') yoziladi. Audit log. Email in-app approverga (agar ClickSettings.refund_approver_role sozlangan — shu roldagi userlarga). Agar approver role yo'q — avtomatik approve.

FR-06-19: POST /admin-panel/refunds/<id>/approve/ — perm payment.refund_approve. status='approved' → Celery submit_click_refund(refund_id) task ishga tushadi.

FR-06-20: Celery task Click /refund endpoint ga API so'rov yuboradi. Retry chain: eksponensial backoff 1min → 4min → 15min → 1soat → 4soat (max 5 urinish, 24 soat oynasi).

FR-06-21: Muvaffaqiyat (callback keladi) → Invoice.status yangilanadi → Submission state cancelled → refunded. SMS+email refund_completed.

3.7 ClickSettings (admin UI)¶

FR-06-22: GET /admin-panel/settings/click/ — perm settings.manage_click. Forma:
- merchant_id, service_id, merchant_user_id — text
- secret_key — password widget, serverda encrypted
- endpoint_url
- is_test_mode toggle
- refund_enabled toggle
- refund_default_kind select (full/partial)
- refund_approver_role FK → Role (nullable — "auto-approve" bo'lishi uchun)

Saqlash — audit log.

FR-06-23: "Test to'lov" tugmasi: perm settings.test_payment. Fake Invoice yaratadi amount=1000 UZS, Click sandbox URL'iga redirect. Callback javobi oxirida Invoice avtomatik o'chiriladi (test-mode flag).

3.8 Adminpanel invoice list¶

Filter: status CSV, method CSV, date range, Submission code qidiruv, amount range.

Saved tabs: Yangi (pending) / To'langan / Bekor qilingan / Qaytarilgan / Barchasi.

Drawer: Invoice detail + ClickTransaction timeline + Refund list.

3.9 Receipt page¶

FR-06-25: GET /payments/<invoice_no>/receipt/ — public. Agar paid holatda — PDF download link va preview. pending — "to'lov kutilmoqda" xabar. cancelled/refunded — mos status chip. Rate limit 20/min/IP.

3.10 Cancel manual¶

FR-06-26: POST /admin-panel/invoices/<id>/cancel/ — perm invoice.cancel. Reason majburiy. Faqat status='pending' holatida. Submission payment_pending → cancelled. Audit log.

4. Data model¶

4.1 `payments.Invoice`¶

class Invoice(TimestampedModel):
    submission = models.ForeignKey(
        'submissions.Submission', on_delete=models.PROTECT,
        related_name='invoices', null=True, blank=True,
    )
    number = models.CharField(max_length=32, unique=True)  # INV-YYYY-NNNNNN
    amount = models.DecimalField(max_digits=14, decimal_places=2)
    currency = models.CharField(max_length=3, default='UZS')

    # Snapshot — Issue sozlamasi o'zgarsa ham invoice summasiga ta'sir etmaydi
    bxm_snapshot = models.DecimalField(max_digits=14, decimal_places=2, null=True)
    price_percent_snapshot = models.DecimalField(max_digits=5, decimal_places=2, null=True)
    price_fixed_snapshot = models.DecimalField(max_digits=14, decimal_places=2, null=True)

    STATUS_CHOICES = [
        ('pending', 'Kutilmoqda'),
        ('paid', "To'landi"),
        ('cancelled', 'Bekor qilindi'),
        ('refunded', 'Qaytarildi'),
        ('partially_refunded', 'Qisman qaytarildi'),
    ]
    status = models.CharField(max_length=24, choices=STATUS_CHOICES, default='pending')

    due_at = models.DateTimeField()
    paid_at = models.DateTimeField(null=True, blank=True)

    METHOD_CHOICES = [
        ('click', 'Click'), ('payme', 'Payme'),
        ('bank_transfer', 'Bank o\'tkazmasi'), ('cash', 'Naqd'),
    ]
    payment_method = models.CharField(max_length=24, choices=METHOD_CHOICES, default='click')

    external_order_id = models.CharField(max_length=64, blank=True)
    legal_entity = models.ForeignKey(
        'payments.LegalEntity', on_delete=models.SET_NULL,
        null=True, blank=True,
    )
    pdf_receipt = models.FileField(upload_to='private/invoices/', null=True, blank=True)

    cancel_reason = models.TextField(blank=True)
    cancelled_by = models.ForeignKey(
        'accounts.User', null=True, blank=True, on_delete=models.SET_NULL,
        related_name='cancelled_invoices',
    )

    class Meta:
        indexes = [
            models.Index(fields=['status', 'due_at']),
            models.Index(fields=['submission', 'status']),
            models.Index(fields=['payment_method', 'status']),
            models.Index(fields=['-created_at']),
        ]
        constraints = [
            models.CheckConstraint(check=models.Q(amount__gt=0), name='invoice_amount_gt0'),
        ]

4.2 `payments.ClickTransaction`¶

class ClickTransaction(TimestampedModel):
    invoice = models.ForeignKey(Invoice, on_delete=models.PROTECT, related_name='click_tx')
    click_trans_id = models.CharField(max_length=64, db_index=True)
    merchant_trans_id = models.CharField(max_length=64, db_index=True)
    merchant_prepare_id = models.CharField(max_length=64, blank=True)
    amount = models.DecimalField(max_digits=14, decimal_places=2)
    action = models.SmallIntegerField()  # -1 cancel, 0 prepare, 1 complete
    sign_time = models.CharField(max_length=32)
    sign_string_received = models.CharField(max_length=64)
    sign_string_expected = models.CharField(max_length=64)
    is_valid_signature = models.BooleanField(default=False)
    error_code = models.IntegerField(default=0)
    error_note = models.CharField(max_length=255, blank=True)
    raw_request = models.JSONField()
    raw_response = models.JSONField()
    client_ip = models.GenericIPAddressField(null=True)

    class Meta:
        constraints = [
            models.UniqueConstraint(
                fields=['click_trans_id', 'action'],
                name='uniq_click_trans_action',
            ),
        ]
        indexes = [
            models.Index(fields=['invoice', 'action']),
            models.Index(fields=['-created_at']),
        ]

4.3 `payments.Refund`¶

class Refund(TimestampedModel):
    invoice = models.ForeignKey(Invoice, on_delete=models.PROTECT, related_name='refunds')
    amount = models.DecimalField(max_digits=14, decimal_places=2)
    reason = models.TextField()
    KIND_CHOICES = [('full', "To'liq"), ('partial', 'Qisman')]
    kind = models.CharField(max_length=16, choices=KIND_CHOICES)

    initiated_by = models.ForeignKey(
        'accounts.User', on_delete=models.PROTECT, related_name='refunds_initiated',
    )
    approved_by = models.ForeignKey(
        'accounts.User', null=True, blank=True, on_delete=models.SET_NULL,
        related_name='refunds_approved',
    )
    approved_at = models.DateTimeField(null=True, blank=True)

    STATUS_CHOICES = [
        ('pending_approval', 'Tasdiq kutilmoqda'),
        ('approved', 'Tasdiqlandi'),
        ('sent_to_gateway', 'Gatewayga yuborildi'),
        ('succeeded', 'Muvaffaqiyatli'),
        ('failed', 'Xato'),
    ]
    status = models.CharField(max_length=24, choices=STATUS_CHOICES, default='pending_approval')

    GATEWAY_CHOICES = [('click', 'Click'), ('payme', 'Payme'), ('bank', 'Bank')]
    gateway = models.CharField(max_length=16, choices=GATEWAY_CHOICES)
    gateway_refund_id = models.CharField(max_length=64, blank=True)
    gateway_response = models.JSONField(default=dict, blank=True)

    retry_count = models.PositiveIntegerField(default=0)
    next_retry_at = models.DateTimeField(null=True, blank=True)
    last_error = models.TextField(blank=True)

    class Meta:
        indexes = [
            models.Index(fields=['status', 'next_retry_at']),
            models.Index(fields=['invoice', 'status']),
        ]
        constraints = [
            models.CheckConstraint(check=models.Q(amount__gt=0), name='refund_amount_gt0'),
        ]

4.4 `payments.ClickSettings` (singleton)¶

class ClickSettings(TimestampedModel):
    merchant_id = models.CharField(max_length=64)
    service_id = models.CharField(max_length=64)
    merchant_user_id = models.CharField(max_length=64)
    secret_key_encrypted = models.BinaryField()          # Fernet(key=settings.DATA_ENCRYPTION_KEY)
    secret_key_version = models.PositiveSmallIntegerField(default=1)
    endpoint_url = models.URLField(default='https://my.click.uz/services/pay')
    is_test_mode = models.BooleanField(default=True)
    refund_enabled = models.BooleanField(default=True)
    refund_default_kind = models.CharField(max_length=16, default='full')
    refund_approver_role = models.ForeignKey(
        'accounts.Role', null=True, blank=True, on_delete=models.SET_NULL,
    )
    allowed_ips = models.JSONField(default=list)         # ["213.230.106.106", ...]

    class Meta:
        constraints = [
            models.UniqueConstraint(
                fields=[],
                condition=models.Q(pk__gt=0),
                name='one_click_settings',
            ),
        ]

    @classmethod
    def get_current(cls) -> 'ClickSettings': ...

    def get_secret_key(self) -> str: ...   # decrypt

Yagona row cheklovi: get_or_create(pk=1) pattern; admin panelda "yaratish" tugmasi yo'q, faqat "tahrir".

4.5 Migrations¶

0001_initial — Invoice + ClickTransaction + Refund + ClickSettings. UniqueConstraint uchun alohida PostgreSQL SQL:

-- Migration 0002: unique partial index for singleton
CREATE UNIQUE INDEX uniq_click_settings_singleton
ON payments_clicksettings ((1));

-- Migration 0003: BRIN index for large-volume invoices (future scale)
CREATE INDEX invoices_created_brin ON payments_invoice USING BRIN (created_at);

-- Migration 0004: partial index for active refunds
CREATE INDEX refunds_active_partial ON payments_refund (next_retry_at)
WHERE status IN ('approved','sent_to_gateway','failed') AND retry_count < 5;

Backfill: Phase 06 greenfield — backfill yo'q.

5. API contracts¶

5.1 `POST /api/click/prepare/`¶

Auth: none (webhook); IP allowlist middleware; signature verification.
Rate limit: CC §2.5 — 120/min/IP.
Content-Type: application/x-www-form-urlencoded (Click standart).

Request fields (form):

click_trans_id   string
service_id       string
click_paydoc_id  string
merchant_trans_id string      (biz Invoice.number)
amount           decimal
action           "0"
error            integer
error_note       string
sign_time        string (YYYY-MM-DD HH:MM:SS)
sign_string      md5 hex

Success response (200):

{
  "click_trans_id": "123456789",
  "merchant_trans_id": "INV-2026-000123",
  "merchant_prepare_id": "42",
  "error": 0,
  "error_note": "Success"
}

Error responses (200 OK, error code body'da — Click spec):

error	error_note	Sabab
-1	SIGN CHECK FAILED	Signature mos kelmadi
-2	Incorrect parameter amount	Amount ≠ Invoice.amount
-3	Action not found	action qiymati 0 emas
-4	Already paid	Invoice.status ≠ 'pending'
-5	User does not exist	Invoice topilmadi
-6	Transaction does not exist	—
-8	Error in request from click	umumiy
-9	Transaction cancelled	—

curl namuna:

curl -X POST https://journal.ktri.uz/api/click/prepare/ \
  -d "click_trans_id=123456789" \
  -d "service_id=67890" \
  -d "merchant_trans_id=INV-2026-000123" \
  -d "amount=75000.00" \
  -d "action=0" \
  -d "error=0" \
  -d "sign_time=2026-04-20 10:30:00" \
  -d "sign_string=$(md5sum <<< '123456789'67890'SECRET'INV-2026-000123'75000.00'0'2026-04-20 10:30:00')"

5.2 `POST /api/click/complete/`¶

Request: prepare bilan bir xil + merchant_prepare_id.

Success response:

{
  "click_trans_id": "123456789",
  "merchant_trans_id": "INV-2026-000123",
  "merchant_confirm_id": "101",
  "error": 0,
  "error_note": "Success"
}

Error codes: prepare bilan bir xil + -4 Already paid (idempotent retry — pre-cached response).

5.3 `POST /api/click/refund-callback/`¶

Request:

{
  "click_trans_id": "123456789",
  "refund_id": "777",
  "amount": 75000.00,
  "status": "succeeded",
  "sign_time": "2026-04-21 15:00:00",
  "sign_string": "<md5>"
}

Response: {"error": 0, "error_note": "OK"} yoki xatolik.

5.4 `GET /payments/<invoice_no>/pay/click/`¶

Auth: none.
Rate limit: 30/min/IP.
Behavior: 302 redirect Click hosted page URL'ga.

5.5 `GET /payments/<invoice_no>/receipt/`¶

Auth: none (invoice_no — opak identifier).
Rate limit: 20/min/IP.
Response: HTML (receipt preview + PDF download link).

404: invoice topilmadi.
410 Gone: cancelled.

5.6 Adminpanel API¶

`GET /admin-panel/api/invoices/`¶

Auth: session + invoice.view.
Query: ?status=pending,paid&method=click&date_from=...&date_to=...&q=<submission_code>&page=...

Javob CC §4.2 format.

{
  "data": [
    {
      "id": 42,
      "number": "INV-2026-000123",
      "submission": {"code": "KTRI-2026-01-A8F3K9", "title": "..."},
      "amount": "75000.00",
      "currency": "UZS",
      "status": "pending",
      "method": "click",
      "created_at": "2026-04-20T10:30:00Z",
      "paid_at": null,
      "due_at": "2026-04-30T10:30:00Z"
    }
  ],
  "meta": {...}
}

`POST /admin-panel/api/invoices/<id>/cancel/`¶

Auth: session + invoice.cancel.
Body: {"reason": "..."}
200: {"data": {"id": 42, "status": "cancelled"}}
422: {"error": {"code": "INVOICE_NOT_PENDING", ...}}

`POST /admin-panel/api/refunds/`¶

Auth: session + payment.refund_initiate.
Body:

{
  "invoice_id": 42,
  "amount": "75000.00",
  "kind": "full",
  "reason": "Muallif maqolani qaytarib oldi..."
}

201: yaratilgan Refund obyekt.
422: AMOUNT_EXCEEDS, REFUND_NOT_ENABLED, INVOICE_NOT_PAID.

`POST /admin-panel/api/refunds/<id>/approve/`¶

Auth: session + payment.refund_approve.

6. Security spec¶

6.1 Threat model (CC §2 ga qo'shimcha)¶

#	Tahdid	Mitigatsiya
T-06-01	Webhook spoof — soxta Click so'rovi	IP allowlist middleware (CC §2.8) + constant-time signature compare; muvaffaqiyatsizlik audit log, 400
T-06-02	Signature forge (secret leak)	Secret pgcrypto/Fernet bilan encrypted; `.env` read-only deploy user; rotation pleyli — `ClickSettings.secret_key_version`
T-06-03	Replay attack — eski webhook qayta yuborish	`(click_trans_id, action)` unique — DB-level dedup; `sign_time` drift ±15min tekshirish
T-06-04	Amount tampering — foydalanuvchi amount=1 so'm yuboradi	Webhook'da `amount == Invoice.amount` qat'iy tenglik; DecimalField kvantatsiya `.quantize(Decimal('0.01'))`
T-06-05	Race condition — ikkita webhook bir vaqtda	`select_for_update(of=('self',))` Invoice satrida; atomic block
T-06-06	IDOR — `invoice_no` ni boshqa kishi bilishi	`invoice.number` 10^6+ keng maydonli; hech qanday sensitive ma'lumot faqat status; pay page ochiq lekin `pending` holatda emas — 410
T-06-07	Refund initiate by unauthorized	`payment.refund_initiate` perm; initiator ≠ approver (segregation of duties) — `initiated_by != approved_by` constraint
T-06-08	Double refund (partial + full)	Application-level check: `sum(existing_refunds.amount) + new_amount <= invoice.amount`
T-06-09	PDF receipt content injection (user-uploaded title)	Reportlab chunked text — no HTML; bleach ishlatilmaydi reportlab API'si parameterised
T-06-10	SSRF in Click API call	Endpoint URL allowlist — faqat `my.click.uz` yoki test domain; `allowed_hosts` validator
T-06-11	Webhook body flood	`client_max_body_size` 16KB nginx tomondan (CC §2.8 1MB, lekin Click payload kichik); ratelimit
T-06-12	Log PII leak (raw_request saqlanadi)	`raw_request` tarkibida parol/token yo'q (Click webhook amount + trans_id); 365 kun TTL scheduled cleanup

6.2 Signature algoritm¶

import hashlib
import hmac

def build_sign(click_trans_id, service_id, secret_key,
               merchant_trans_id, amount, action, sign_time) -> str:
    # Amount — exactly as Click sends: "75000.00" (not scientific, not int)
    raw = f"{click_trans_id}{service_id}{secret_key}{merchant_trans_id}{amount}{action}{sign_time}"
    return hashlib.md5(raw.encode('utf-8')).hexdigest()

def verify(received: str, expected: str) -> bool:
    return hmac.compare_digest(received, expected)

Kritik: amount formatlash — Click tomondan qanday kelgan bo'lsa, shu string asl holicha ishlatiladi (float → string konversiyasi qilinmaydi; request.POST['amount'] raw). Agar Click 75000.00 yubordi, biz 75000 deb hisoblasak signature fail bo'ladi.

Complete action uchun signature raw:

{click_trans_id}{service_id}{secret}{merchant_trans_id}{merchant_prepare_id}{amount}{action}{sign_time}

6.3 IP allowlist middleware¶

# payments/middleware.py
class ClickIPAllowlistMiddleware:
    def __init__(self, get_response): ...
    def __call__(self, request):
        if request.path.startswith('/api/click/'):
            client_ip = self._resolve_ip(request)
            allowed = ClickSettings.get_current().allowed_ips + CLICK_ALLOWED_IPS_FALLBACK
            if client_ip not in allowed:
                AuditLog.log('click_ip_rejected', ip=client_ip, meta={'path': request.path})
                return JsonResponse({'error': -8, 'error_note': 'IP not allowed'}, status=403)
        return self.get_response(request)

X-Forwarded-For — faqat trusted proxy (Nginx) orqali (CC §2.3).

6.4 Sessiya + CSRF¶

Webhook endpoints @csrf_exempt dekoratori bilan (Click tomondan cookie yubormaydi). Admin panel forma'lar — CSRF majburiy (Django default).

6.5 Secret rotation¶

Yangi secret kiritish: ClickSettings.secret_key_encrypted yangilanadi, secret_key_version += 1.
Click kabinetda parallel secret yuklanadi (agar Click qo'llab-quvvatlasa — yo'q bo'lsa rotation downtime talab etadi; "maintenance mode" flag).
Audit log.

6.6 PII va maxfiylik¶

Invoice'da PII yo'q (submission FK bor — u orqali ismga borish mumkin, lekin kim Invoice'ni ko'rsa, invoice.view perm bor). Webhook raw payload'da ism yo'q.

7. Optimization spec¶

7.1 Query plan¶

Invoice list (admin):

Invoice.objects.select_related('submission').only(
    'id', 'number', 'amount', 'currency', 'status', 'payment_method',
    'created_at', 'paid_at', 'due_at',
    'submission__code', 'submission__title_uz',
).order_by('-created_at')

Filter indekslar (§4.5) — status, payment_method, created_at — hammasi covered.

Invoice detail:

Invoice.objects.select_related('submission', 'legal_entity')\
    .prefetch_related(
        Prefetch('click_tx', queryset=ClickTransaction.objects.order_by('-created_at')),
        'refunds',
    ).get(id=pk)

7.2 Cache layers¶

Kalit	TTL	Invalidatsiya
`kj:click:settings:v1`	5min	`ClickSettings.save()` signal
`kj:payments:invoice_count:pending`	60s	Celery beat har 30s refresh (dashboard stat)
`kj:payments:bxm:current`	24h	`BxmSetting.save()` signal

Webhook endpointlari cache ishlatmaydi (tranzaksional).

7.3 Celery queue mapping¶

Task	Queue	Soft/Hard	Retry
`generate_receipt_pdf(invoice_id)`	`q:default`	30s/60s	3×, exp backoff
`submit_click_refund(refund_id)`	`q:default`	60s/120s	5×, exp (1m, 4m, 15m, 1h, 4h)
`cancel_overdue_invoices()` (beat hourly)	`q:low`	60s/120s	—
`cleanup_old_click_raw_payloads()` (beat daily)	`q:low`	120s/180s	—

7.4 Performance budget (CC §3.8 dan)¶

Endpoint	P50	P95	P99
`POST /api/click/prepare/`	40ms	120ms	250ms
`POST /api/click/complete/`	50ms	150ms	300ms
`POST /api/click/refund-callback/`	40ms	120ms	250ms
`GET /payments/<no>/pay/click/`	20ms	60ms	150ms
`GET /payments/<no>/receipt/`	60ms	150ms	400ms
`GET /admin-panel/invoices/` (20 items)	150ms	400ms	900ms

7.5 DB concurrency¶

PgBouncer transaction-mode: webhook SELECT FOR UPDATE oynasi maksimum 200ms bo'lishi kerak (signature+verify+update+signal). Celery task'lar — alohida connection pool.

8. Validation rules¶

Field	Qoida
`Invoice.number`	regex `^INV-\d{4}-\d{6}$`; unique
`Invoice.amount`	`> 0`, `<= 1000000000` (1 mlrd so'm upper bound)
`Invoice.currency`	default `UZS`; allowlist `['UZS']` MVP
`Invoice.payment_method`	enum; default `click`
`Invoice.due_at`	`> created_at + 1 kun`, `< created_at + 90 kun`
`ClickTransaction.action`	in `{-1, 0, 1}`
`ClickTransaction.amount`	`> 0`
`ClickTransaction.sign_time`	parse `YYYY-MM-DD HH:MM:SS`, drift ±15min server bilan
`Refund.amount`	`> 0`, `<= Invoice.amount - sum(siblings.amount)`
`Refund.reason`	`min_length=20`
`Refund.kind`	`full` bo'lsa `amount == Invoice.amount`; `partial` bo'lsa `< Invoice.amount`
`ClickSettings.merchant_id`	numeric string, 5–10 chars
`ClickSettings.allowed_ips`	each element — valid IPv4

9. Error handling¶

9.1 Exception ierarxiyasi¶

payments.exceptions
├── PaymentError (base)
│   ├── InvoiceError
│   │   ├── InvoiceNotFound
│   │   ├── InvoiceNotPending
│   │   ├── InvoiceAmountMismatch
│   │   └── InvoiceDueExpired
│   ├── SignatureError
│   │   ├── SignatureMismatch
│   │   └── SignatureTimeDrift
│   ├── RefundError
│   │   ├── RefundAmountExceeds
│   │   ├── RefundNotEnabled
│   │   └── RefundAlreadyIssued
│   └── GatewayError
│       ├── ClickGatewayTimeout
│       └── ClickGatewayUnreachable

9.2 HTTP mapping¶

Exception	Webhook (Click)	Adminpanel
`InvoiceNotFound`	`{error: -5}`, 200	404 `INVOICE_NOT_FOUND`
`InvoiceNotPending`	`{error: -4}`, 200	422 `INVOICE_NOT_PENDING`
`InvoiceAmountMismatch`	`{error: -2}`, 200	422 `AMOUNT_MISMATCH`
`SignatureMismatch`	`{error: -1}`, 200	—
`SignatureTimeDrift`	`{error: -1}`, 200	—
`RefundAmountExceeds`	—	422 `REFUND_AMOUNT_EXCEEDS`
`RefundNotEnabled`	—	403 `REFUND_NOT_ENABLED`
`ClickGatewayTimeout`	—	503 (Celery retry)

9.3 User-facing xabarlar¶

Receipt/pay page HTML — i18n:

Case	uz	ru	en
pending	"To'lov kutilmoqda. Havola orqali to'lang."	"Ожидается оплата. Перейдите по ссылке."	"Payment pending. Proceed via link."
paid	"To'lov muvaffaqiyatli amalga oshirildi."	"Оплата успешно произведена."	"Payment successful."
cancelled	"To'lov bekor qilindi."	"Платёж отменён."	"Payment cancelled."
refunded	"To'lov qaytarildi."	"Платёж возвращён."	"Payment refunded."
invoice_not_found	"Invoice topilmadi."	"Счёт не найден."	"Invoice not found."
amount_mismatch (admin)	"Summa mos kelmadi."	"Сумма не совпадает."	"Amount mismatch."
refund_pending_approval	"Qaytarish tasdiq kutilmoqda."	"Возврат ожидает подтверждения."	"Refund pending approval."
refund_succeeded	"Qaytarish muvaffaqiyatli."	"Возврат выполнен."	"Refund succeeded."

9.4 Logging strategy¶

Webhook har chaqiriqda structured log:

{
  "event": "click.prepare.received",
  "click_trans_id": "...",
  "invoice_number": "INV-2026-000123",
  "signature_valid": true,
  "client_ip": "213.230.106.106",
  "duration_ms": 42,
  "action": 0,
  "error_code": 0
}

ValueError/SignatureError — WARN; IntegrityError duplicate — INFO (expected idempotency); 5xx — Sentry.

10. Observability¶

10.1 Metrics (Prometheus)¶

payments_invoice_total{status="pending|paid|..."} — gauge
payments_click_webhook_duration_seconds{action="0|1|-1"} — histogram
payments_click_signature_failures_total — counter
payments_click_ip_rejected_total — counter
payments_refund_duration_seconds{status} — histogram
payments_invoice_amount_sum{currency="UZS",status="paid"} — counter (business)
payments_overdue_cancelled_total — counter (beat task)

10.2 Audit log actions¶

Kod	Target	Kim
`invoice_created`	Invoice	system / user
`invoice_cancelled_manual`	Invoice	accountant/admin
`invoice_cancelled_overdue`	Invoice	system (beat)
`click_signature_invalid`	ClickTransaction	system
`click_ip_rejected`	— (meta.ip)	system
`refund_initiated`	Refund	accountant/admin
`refund_approved`	Refund	approver
`refund_succeeded`	Refund	system
`refund_failed`	Refund	system
`click_settings_updated`	ClickSettings	super_admin
`click_test_payment_created`	Invoice	super_admin

10.3 Sentry tags¶

payment_method=click, invoice_number=..., submission_code=..., click_trans_id=..., signature_valid=.... Pre-filter raw_request/raw_response payload'dagi sign_string'ni mask qilish — forensics qolsin deb raw_request DB'da to'liq, Sentry'ga mask.

10.4 Business event¶

Emit payments.invoice_paid(invoice_id, submission_id, amount) — keyin notifications app (Phase 10) ushbuni eshitib SMS/email yuboradi.

10.5 Log fields¶

request_id — CC §4.2
click_trans_id, merchant_trans_id
action
invoice_number
user_id (admin amaliyotida)
client_ip
duration_ms

11. Test plan¶

11.1 Unit¶

test_build_sign__matches_click_example
test_build_sign__amount_string_preservation
test_verify_signature__constant_time
test_verify_signature__mismatch_returns_false
test_invoice_number_atomic_counter__concurrent_1000
test_calc_amount__bxm_percent
test_calc_amount__fixed_soum
test_calc_amount__snapshots_preserved_after_bxm_change
test_refund_amount__exceeds_invoice_raises
test_refund_amount__partial_plus_full_exceeds_raises
test_click_settings_singleton__second_insert_fails
test_click_settings_secret__encrypt_decrypt_roundtrip
test_refund_kind_full__amount_must_equal_invoice

11.2 Integration¶

test_prepare_webhook__happy_path_returns_error_0
test_prepare_webhook__signature_mismatch_returns_minus1_and_audit_logged
test_prepare_webhook__ip_not_allowed_returns_403
test_prepare_webhook__amount_mismatch_returns_minus2
test_prepare_webhook__invoice_not_pending_returns_minus4
test_prepare_webhook__duplicate_returns_cached_response
test_complete_webhook__happy_transitions_state_paid
test_complete_webhook__triggers_submission_transition
test_complete_webhook__generates_pdf_receipt_via_celery
test_complete_webhook__race_condition_select_for_update
test_complete_webhook__action_minus1_cancels_invoice
test_refund_callback__success_updates_invoice_refunded
test_refund_callback__partial_updates_status_partially_refunded
test_refund_callback__failed_triggers_retry_schedule
test_invoice_auto_create__on_apc_accepted_transition
test_invoice_auto_create__on_upfront_desk_review_forward
test_invoice_auto_create__free_mode_no_invoice
test_pay_page__redirect_click_url_with_correct_params
test_pay_page__not_pending_returns_410
test_receipt_page__paid_shows_pdf_link
test_admin_invoice_list__filter_by_status_method
test_admin_invoice_cancel__audit_logged
test_admin_refund_create__without_approver_auto_approves
test_admin_refund_approve__requires_different_user_than_initiator
test_admin_refund_approve__triggers_celery_task
test_overdue_cancellation_beat__cancels_pending_past_due
test_click_settings_update__invalidates_cache

11.3 Security¶

sec_test_webhook__signature_replay_same_action_returns_cached
sec_test_webhook__signature_replay_modified_amount_fails
sec_test_webhook__signtime_drift_16min_returns_minus1
sec_test_webhook__ip_x_forwarded_for_spoof_ignored_unless_trusted_proxy
sec_test_admin_refund__without_perm_returns_403
sec_test_admin_invoice_cancel__without_perm_returns_403
sec_test_settings_secret__plaintext_not_in_admin_list_response
sec_test_audit_log__failed_signature_row_created
sec_test_webhook__body_over_1mb_rejected_413
sec_test_ssrf__click_endpoint_url_only_official_domains
sec_test_csrf__admin_refund_post_without_token_rejected
sec_test_idor__another_user_cannot_view_invoice_without_perm

11.4 Performance¶

k6 smoke: 20 RPS prepare+complete har biri 60s — P95 < 150ms
k6 load: 100 RPS 5 daqiqa — no 5xx, CPU < 60%
Stress: 500 RPS 1min — degradation tavsiflangan (throttle 429 dan keyin)
DB: 10k pending invoice'li filterda query plan — indeks ishlayapti (EXPLAIN ANALYZE)

11.5 E2E (Playwright)¶

e2e_author_pay_click_sandbox_full_flow — Submission wizard → state → Invoice → pay page → Click sandbox → webhook → paid → receipt
e2e_accountant_cancel_invoice — adminpanel Invoice cancel flow
e2e_accountant_refund_flow — initiate → approve → gateway → refunded

12. Acceptance criteria¶

Quyidagi har bir band tashqi tekshiruvchi tomonidan manual yoki avtomat ijrodir:

[ ] Submission apc_after_accept bilan accepted holatga o'tgach, 5 soniya ichida pending Invoice yaratiladi (Celery queue latency).
[ ] Invoice number ketma-ket atomic (1000 concurrent test — duplicate yo'q).
[ ] amount = BXM × percent snapshot bilan — BXM sozlamasi keyinchalik o'zgarsa, oldingi Invoice o'zgarmaydi.
[ ] Click sandbox prepare → complete → Invoice.status='paid', Submission.state='paid'.
[ ] Click sandbox'da 2 marta aynan bir xil click_trans_id + action=1 yuboriladi — ikkinchi javob cached; DB'da 1 ta ClickTransaction.
[ ] Noto'g'ri signature — error=-1, AuditLog yozuvi, Invoice status o'zgarmaydi.
[ ] IP allowlist'dan tashqaridan so'rov — 403.
[ ] sign_time 20 daqiqa oldin — error=-1.
[ ] Amount mos kelmasa — error=-2, Invoice pending qoladi.
[ ] Pay page 302 redirect to'g'ri parametrlar bilan.
[ ] Receipt PDF Celery orqali generatsiya qilinadi, Invoice.pdf_receipt to'ldiriladi.
[ ] Adminpanel invoice list filter saved tabs ishlaydi; P95 < 400ms 20 item'da.
[ ] Manual cancel — reason yozilgan bo'lsa status=cancelled, Submission ham cancelled.
[ ] Overdue Invoice (10 kundan oshgan pending) beat task orqali cancelled bo'ladi.
[ ] Refund initiate → pending_approval (approver role sozlangan). Initiator o'zi approve qila olmaydi.
[ ] Refund approve → Celery task → Click sandbox /refund API → callback → Invoice.status='refunded', Submission cancelled → refunded.
[ ] Partial refund: Invoice.status='partially_refunded'. Qolgan summaga ikkinchi partial refund mumkin, lekin birga qo'shilib > Invoice.amount bo'lolmaydi.
[ ] ClickSettings admin sahifada secret_key plaintext ko'rinmaydi (password widget); yangilash audit log.
[ ] Test payment button — dummy Invoice yaratib, sandbox sikl yakunida Invoice o'chiriladi.
[ ] Webhook endpointlari @csrf_exempt, adminpanel formalari CSRF required.
[ ] raw_request/raw_response JSONField'da to'liq saqlanadi; 365 kundan keyin beat task orqali tozalanadi.
[ ] k6 smoke CI — P95 budgeti ichida.
[ ] Audit log actions barcha 11 kod (§10.2) ishlagan — integration test mavjud.

13. Rollout¶

13.1 Migration¶

Deploy A (schema):
payments/migrations/0001_initial.py — 4 ta model, hech qanday data.
0002_click_settings_singleton_constraint.py — CREATE UNIQUE INDEX.
0003_invoice_created_brin.py (CONCURRENTLY, atomic=False).
0004_refund_active_partial.py (CONCURRENTLY).
Seed:
core/management/commands/seed_payments.py — ClickSettings is_test_mode=True bilan, secret placeholder.
Permissions seed: invoice.view/create_manual/cancel, payment.refund_initiate/approve, settings.manage_click, settings.test_payment.
Backfill: yo'q (greenfield).

13.2 Feature flags (waffle)¶

Flag	Default	Maqsad
`click_payments_enabled`	False (dev/stage), True (prod, stage 2 da)	Webhook endpointlar faol
`refund_auto_approval`	False	Approver role bo'lmasa avtomatik approve
`click_test_mode_banner`	True	Adminpanelda "Sandbox" banner ko'rsatish
`invoice_auto_cancel_beat`	True	Overdue beat task toggle

13.3 Rollout steps¶

Stage 1 (staging): sandbox credentials, is_test_mode=True, flag click_payments_enabled=True. Sintetik test foydalanuvchi bilan to'liq sikl.
Stage 2 (canary): production secrets, is_test_mode=False, flag 10% foydalanuvchi (waffle percentage). 3 kun monitoring.
Stage 3 (full): flag 100%. Click kabineti'dan real webhook IP'lar yozib qo'yiladi.

13.4 Rollback¶

Flag off — webhook endpointlar 503 bilan javob qaytaradi (Click server'da pending transactions sumamasi, keyin qayta yuboradi — idempotent).
Migration rollback: Refund → ClickTransaction → Invoice (FK reverse order). Agar paid Invoice'lar mavjud bo'lsa, migration rollback ruxsat etilmaydi — manual data export + revoke.
Gateway-level rollback: Click kabinetda "Merchant suspended" — ruxsat, bizning webhook'larimiz hali ham raw_request yozadi, lekin 503 qaytaradi.

13.5 Monitoring post-rollout¶

Birinchi 72 soat Sentry + Prometheus dashboard'da:
- payments_click_signature_failures_total > 1/min — alert
- payments_click_webhook_duration_seconds P95 > 300ms — alert
- payments_refund_duration_seconds retry count > 10 — alert
- Invoice pending count o'sish tezligi > 50/soat — alert (Click outage belgisi)

14. Risklar va open questions¶

14.1 Risklar¶

#	Risk	Ta'sir	Mitigatsiya
R-06-01	Click API down — author pay page 500	Yuqori	pay page HTML fallback: "Click xizmati vaqtinchalik mavjud emas. Keyinroq urinib ko'ring." + Payme link (Phase 09 dan keyin)
R-06-02	Secret leak via git history	Katastrofik	.env git-ignore, `git-secrets` pre-commit hook (CC §2.9); rotation playbook tayyor
R-06-03	Timezone drift webhook `sign_time` bilan — UTC/Tashkent	O'rta	Server UTC; `sign_time` `Asia/Tashkent` assumed (Click docs); explicit `tzconvert` + ±15min tolerance
R-06-04	Duplicate Invoice creation due to signal retry	O'rta	Signal handler idempotency — `get_or_create` on `(submission, status='pending')`
R-06-05	Refund retry storm	O'rta	Exp backoff + max 5 attempts; Celery rate_limit `20/m` task darajasida
R-06-06	Amount rounding bug (BXM × percent → 75000.001)	Yuqori	`Decimal` arithmetic, `.quantize(Decimal('0.01'), ROUND_HALF_UP)` — unit test
R-06-07	Click API ma'lumot formati o'zgarishi	O'rta	`raw_request`/`raw_response` full audit — tezkor triage mumkin
R-06-08	Concurrent webhook: prepare + complete bir vaqtda	O'rta	`select_for_update(of=('self',))` + unique constraint
R-06-09	Invoice overdue cancel Celery beat miss	Past	idempotent — 10 minut buffer; manual re-run safe
R-06-10	Yuridik shaxs (legal entity) invoice Phase 09 kiradi — shu faza'da `legal_entity_id nullable` qoldirilishi	Past	null tekshirish joylari (`hasattr`) documented

14.2 Open questions (user decision kerak)¶

Click refund API rasmiy hujjati: Click Merchant v2 hujjatida refund endpoint URL aniq emas. Tasdiqlash kerak: /refund yoki /services/pay/refund? Sandbox test bilan aniqlanadi.
Refund approver role default: accountant yoki admin? Taklif: accountant (SoD — payment.refund_initiate initiator boshqa, approver boshqa).
Invoice due_at default: 10 kun. Issue darajasida override kerakmi (Phase 07 bilan bog'liq)? Plan'da 10 kun default — tasdiqlash.
Multi-currency: MVP faqat UZS. Kelajakda USD ACP (xalqaro muallif)? Alohida phase.
Receipt PDF til: muallifning lang bo'yicha (uz/ru/en) yoki har doim uz? Taklif: muallif lang.
Cash payment: plan'da payment_method='cash' bor — kim yoqadi? Hozircha skip; admin manual Invoice.status='paid' qilish mumkinmi? Tasdiqlash.
Duplicate Invoice suppressor: agar Submission payment_pending holatida turib user refresh qilsa va yangi invoice trigger bo'lsa — get_or_create(submission, status='pending') mos keladi, lekin amount o'zgargan bo'lsa? Plan: "bir submissionga faqat bitta pending invoice".
Webhook timeout Click tomondan: Click 10s timeout. Bizim P95 150ms — margin katta, lekin Celery queue kechikishi? PDF generatsiya webhook'dan ajratilgan (task) — OK.
ClickSettings.allowed_ips seed: Click rasmiy IP rangelari hujjatda — 3 ta IP. KTRI admin'i tekshirishi shart.
refund_enabled=False bo'lsa UI: refund tugmasi umuman ko'rinmaydimi yoki disabled? Taklif: ko'rinmaydi.

Oxiri. Keyingi: Phase 07 — Issue Publish & Article Creation.