v1 · api.cardhook.uz

CardHook

Karta o'tkazmasini buyurtmaga bog'laydi — avtomatik

      —Hisob·Noyob summa·Bank xabari·Callback—
    

PLATFORMA

CARDHOOK API

BANK TOMONI

star.uz — to'lov sahifasi

buyurtma #order-123 29:45

100 Stars 24 000 so'm

TO'LOV SUMMASI 24 017 so'm aynan shu summani o'tkazing — 1 so'm farq ham qabul qilinmaydi

HUMOkarta

9860 1701 1203 0268 ISM FAMILIYA

status: pending → paid Telegram bot Veb-sayt

POST /v1/invoices

Authorization: Bearer pbx_****
{ "external_id": "order-123",
  "amount": 24000,
  "callback_url": "star.uz/…" }

201 Created JSON

{ "invoice_id": "inv_9f2a…",
  "amount": 24000,
  "pay_amount": 24017, ← noyob
  "card": { "bank": "HUMO",
    "number": "9860 …0268" },
  "status": "pending",
  "expires_at": "…10:30Z" }

POST callback_url · HMAC-SHA256

X-Signature: sha256=9b1f…
{ "paid_amount": 24017,
  "status": "paid" }

QABUL KARTASI HUMO · 9860 **** **** 0268 mijoz o'tkazmasi shu kartaga keladi

XABAR KANALLARI

Gmail / IMAPbank e-mail

TelegramSMS-forward

HTTP webhooktashqi tizim

Qo'lda tasdiqlashadmin

MOSLIK MEXANIZMI

◆Xabardagi 24 017 summani faqat bitta hisob kutmoqda

◆Har xabarning sha1 barmoq izi — dubl o'tmaydi

◆Bazada qisman unique indeks — poyga holatida ham himoya

◆Ikkita hisob mos kelsa — taxmin yo'q, admin hal qiladi

QANDAY ISHLAYDI

1 Hisob yaratiladi

POST /v1/invoices — noyob pay_amount qaytadi

→

2 Mijozga ko'rsatiladi

Karta raqami va aniq summa

→

3 O'tkazma keladi

Humo yoki Uzcard kartasiga

→

4 Xabar tahlil qilinadi

Summa bo'yicha hisob topiladi

→

5 Callback yuboriladi

HMAC imzo · 6 martagacha urinish

REAL MISOL · Python

# hisob yaratish
r = requests.post(
    "https://api.cardhook.uz/v1/invoices",
    headers={"Authorization": f"Bearer {KEY}"},
    json={"external_id": "order-123",
          "amount": 24000,
          "callback_url": CALLBACK},
)
inv = r.json()
show(inv["pay_amount"])  # 24017

MA'LUMOT OQIMI

so'rov
keladi →

API

→ callback
qaytadi

24 000 → 24 017 → paid

CHEKLOVLAR

Rate limit60 / daqiqa

Hisob muddati30 daqiqa

Bir summa uchun100 variant

Summa mosligianiq, ±0

Qisman to'lovyo'q

JONLI DEMO

HISOB YARATISH · simulyatsiya external_id amount (so'm)

Bu simulyatsiya — hech qanday so'rov yuborilmaydi. Noyob qo'shimcha (0..99) tasodifiy tanlanadi.

// hisob yaratish tugmasini bosing

{
  "invoice_id": "",
  "external_id": "",
  "amount": ,
  "pay_amount": ,  ← noyob summa
  "card": { "bank": "HUMO", "number": "9860 …0268" },
  "status": "",
  "paid_at": 
}

→ POST callback_url · X-Signature: sha256=… · "status": "paid" ✓

API

curl -X POST https://api.cardhook.uz/v1/invoices \
  -H "Authorization: Bearer pbx_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "order-123",
    "amount": 24000,
    "callback_url": "https://star.uz/cardhook/callback",
    "expires_in": 1800,
    "description": "100 Stars"
  }'

import requests

r = requests.post(
    "https://api.cardhook.uz/v1/invoices",
    headers={"Authorization": "Bearer pbx_xxxxxxxx"},
    json={
        "external_id": "order-123",
        "amount": 24000,
        "callback_url": "https://star.uz/cardhook/callback",
    },
)
invoice = r.json()

const r = await fetch("https://api.cardhook.uz/v1/invoices", {
  method: "POST",
  headers: {
    Authorization: "Bearer pbx_xxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    external_id: "order-123",
    amount: 24000,
    callback_url: "https://star.uz/cardhook/callback",
  }),
});
const invoice = await r.json();

ENDPOINTLAR

POST/v1/invoices

GET/v1/invoices/{id}

GET/v1/invoices?external_id=…

POST/v1/invoices/{id}/cancel

CALLBACK IMZOSINI TEKSHIRISH

expected = "sha256=" + hmac.new(
    secret.encode(),
    timestamp.encode() + b"." + raw_body,
    hashlib.sha256,
).hexdigest()
hmac.compare_digest(signature, expected)

QAYTA URINISH · 6 marta

Qabul qiluvchi invoice_id bo'yicha idempotent bo'lishi shart.

XATOLAR

KOD	HTTP	QACHON
invalid_amount	400	summa butun son emas yoki chegaradan tashqarida
invalid_request	400	external_id bo'sh, JSON buzuq yoki expires_in noto'g'ri
unauthorized	401	kalit yo'q, noto'g'ri yoki merchant o'chirilgan
not_found	404	hisob topilmadi
already_paid	409	to'langan hisobni bekor qilishga urinish
no_free_amount	409	shu summa uchun barcha 100 variant band
rate_limited	429	daqiqalik limitdan oshdi (60 so'rov/daqiqa)

FOYDALANISH SHARTLARI

1Xizmat doirasi

Kelgan o'tkazmani aniqlaydi va hisobga bog'laydi. To'lovni o'zi o'tkazmaydi, qaytarmaydi, ushlab turmaydi.

2Ichki vosita

Egasining o'z platformalari uchun. Uchinchi shaxslar nomidan to'lov qabul qilish xizmati emas.

3Karta ma'lumotlari

Mijozdan PAN, CVV, PIN so'ralmaydi va saqlanmaydi — faqat o'z kartasiga kelgan o'tkazma kutiladi.

4Aniq summa

Qisman to'lov qabul qilinmaydi; 1 so'm farq ham hisobga bog'lanmaydi. Noaniq holat admin orqali hal qilinadi.

5Muddat va bekor qilish

Default 30 daqiqa (60s..24h). Muddati o'tsa expired, summa bo'shaydi. Paid hisob bekor qilinmaydi.

6API kalitlari

Maxfiy. Kalit orqali qilingan barcha so'rovlar egasining javobgarligida. Oshkor bo'lsa — darhol xabar bering.

7Ma'lumotlar

Saqlanadi: summa, karta oxirgi 4 raqami, xabar matni va sha1 izi. 12 oy — so'ng arxiv yoki o'chirish.

8Kafolatlar

Xizmat "as is". Aniqlash tezligi bank xabari kelishiga bog'liq — bank kanalidagi kechikish uchun javobgarlik yo'q.

9Aloqa

Kalit olish va integratsiya savollari: dev@cardhook.uz

Integratsiyaga tayyormisiz? Yopiq servis — API kalitlari qo'lda beriladi. Ro'yxatdan o'tish yo'q.