Savdogar konfiguratsiyasi

Unitel Fintech platformasi API bilan ishlash uchun zarur konfiguratsiya ma'lumotlari.

Base URL

url

https://unitcore.uz/bot/

Autentifikatsiya

Barcha so'rovlar uchun Authorization headerida sizga berilgan Bearer token (API_KEY) va tanangizda yoki headerda Merchant ID yuborilishi shart.

Header Parametr	Turi	Tavsif
Authorization	string	`Bearer SIZNING_API_KALITINGIZ` ko'rinishida yuboriladi.
Merchant-ID	string	(Ixtiyoriy header) Agar so'rov tanasida (JSON) yuborilmasa, header orqali berasiz.

ℹ️ Eslatma: Barcha kredensiallar (API\_KEY va Merchant\_ID) UNITEL tizimi administratori tomonidan taqdim etiladi.

Misol uchun so'rov

http

123

Authorization: Bearer ab12cd34ef56gh78
Merchant-ID: 1053
Content-Type: application/json

Savdogar API integratsiyasi qo'llanmasi

UNITEL Fintech platformasi orqali savdoni boshlash uchun umumiy to'lov oqimi batafsil tushuntiriladi.

To'lov oqimi

Standart to'lov jarayoni quyidagi bosqichlardan iborat:

Bosqich	Endpoint	Tavsif
1	Create Link	To'lov havolasini yaratish va foydalanuvchini yo'naltirish
2	Checkout	Foydalanuvchi to'lov sahifasida karta ma'lumotlarini kiritadi
3	Callback	To'lov natijasi savdogar serveriga yuboriladi
4	Check	Savdogar tranzaksiya holatini tekshiradi

To'lov hayot tsikli (Lifecycle)

Tizimda to'lovlar 3 ta asosiy holatdan o'tadi:

Check (Tekshirish): To'lov yaratishdan oldin tizimning tayyorligini tekshirish.
Create (Yaratish): To'lov kvitansiyasini yaratish (holati: created).
Perform (Bajarish): To'lovni yakunlash va pulni qabul qilish (holati: success).

Eslatma: To'lov havolasi (Payment Link) ishlatilganda "Perform" bosqichi bizning checkout sahifamizda avtomatik bajariladi.

Callback URL

To'lov muvaffaqiyatli amalga oshirilgandan so'ng, tizim sizning callback_url manzilingizga natijani POST qiladi.

json

1234567

{
  "transaction_id": "8910001234",
  "amount": 500,
  "status": 1,
  "order_id": "1001",
  "paid_at": "2026-04-10T12:00:00Z"
}

⚠️ Xavfsizlik: Callback URL ni Basic Auth bilan himoyalash tavsiya etiladi.

To'lov havolasi yaratish

Foydalanuvchini to'lov sahifasiga yo'naltirish uchun to'lov havolasi yaratiladi.

ℹ️ Eslatma: Callback URL so'rovda yuborilishi shart emas. Siz har bir kassa (checkout) uchun alohida Callback URL manzilini shaxsiy kabinetingiz orqali sozlashingiz mumkin. To'lov muvaffaqiyatli yakunlanganda tizim avtomatik ravishda o'sha manzilga natijani yuboradi.

Endpoint details

POST BASE_URL/merchant/pay/link

Header: Authorization: Bearer API_KALIT (va ixtiyoriy Merchant-ID)

Request body

Fields	Type	Required	Description
amount	integer	Yes	Summa (so'mda (UZS))
order_id	string	Yes	Buyurtma raqami (Invoice ID)
return_url	string	No	To'lovdan keyin qaytish manzili

json

12345

{
  "amount": 1000,
  "order_id": "order_1001",
  "return_url": "https://site.uz/success"
}

Success response

json

123456

{
  "result": {
    "checkout_url": "https://unitcore.uz/bot/webapp/checkout.php?invoice_id=8910001234",
    "transaction_id": "8910001234"
  },
  "error": null
}

Error response

json

1234567

{
  "result": null,
  "error": {
    "code": "missing_params",
    "message": "amount and order_id are required"
  }
}

Tranzaksiya tekshiruvi

Tranzaksiya holatini so'rash va tekshirish.

Endpoint details

POST BASE_URL/merchant/receipts/check/

Header: Authorization: Bearer API_KALIT (va ixtiyoriy Merchant-ID)

Request body

Fields	Type	Required	Description
transaction_id	string	Yes	Tranzaksiya identifikatori

json

123

{
  "transaction_id": "8910001234"
}

Success response

json

12345678

{
  "result": {
    "transaction_id": "8910001234",
    "amount": 1000,
    "status": 1,
    "status_name": "success"
  },
  "error": null
}

Tranzaksiya holatlari (Statuslar)

Javobdagi status (raqam) – dasturiy mantiq uchun, status_name (matn) – inson o'qishi uchun ishlatiladi.

Kod (status)	Nom (status_name)	Tavsif
0	`created`	Tranzaksiya yaratilgan, to'lov kutilmoqda
1	`success`	To'lov muvaffaqiyatli amalga oshirildi
-1	`canceled`	To'lov bekor qilingan yoki rad etilgan
3	`charged`	Hold mablag' yechib olindi (faqat Hold uchun)

Error response

json

1234567

{
  "result": null,
  "error": {
    "code": "transaction_not_found",
    "message": "Transaction not found"
  }
}

Tranzaksiyani bajarish

Yaratilgan tranzaksiyani tasdiqlash va to'lovni amalga oshirish.

Endpoint details

POST BASE_URL/merchant/receipts/confirm/

Header: Authorization: Bearer API_KALIT (va ixtiyoriy Merchant-ID)

Request body

Fields	Type	Required	Description
transaction_id	string	Yes	Tranzaksiya identifikatori

Success response

json

123456

{
  "result": {
    "status": 1
  },
  "error": null
}

Error response

json

1234567

{
  "result": null,
  "error": {
    "code": "already_paid",
    "message": "Transaction is already paid"
  }
}

Statuslar

Tranzaksiya va to'lov holatlari uchun ishlatiladigan status kodlari.

Tranzaksiya statuslari

Kod	Status	Tavsif
0	Kutilmoqda	Tranzaksiya yaratilgan, to'lov kutilmoqda
1	To'langan	To'lov muvaffaqiyatli amalga oshirildi
-1	Bekor qilingan	To'lov bekor qilindi yoki qaytarildi
-2	Muddati o'tgan	To'lov vaqti tugagan
2	Ushlab turilgan	Mablag' hold qilingan (faqat Hold Payment)
3	Tasdiqlangan	Hold mablag' yechib olindi

Xato kodlari

Kod	Tavsif
invalid_card_number	Noto'g'ri karta raqami
card_is_already_activated	Karta allaqachon faollashtirilgan
insufficient_funds	Hisobda mablag' yetarli emas
card_expired	Karta muddati o'tgan
invalid_otp	Noto'g'ri SMS kod
transaction_not_found	Tranzaksiya topilmadi
unauthorized	Avtorizatsiya xatosi

Obuna

Obuna (Subscribe) API foydalanuvchi kartalarini saqlash va keyinchalik ulardan to'lov yechish imkonini beradi. Bu usul takroriy to'lovlar va bir martalik to'lovlar uchun ishlatiladi.

To'lov oqimi

Bosqich	Endpoint	Tavsif
1	CreateCard	Karta raqamini yuborish, SMS olinadi
2	ConfirmCard	SMS-kodni kiritish va kartani faollashtirish
3	CreateReceipt	To'lov kvitansiyasini yaratish
4	PayReceipt	Kvitansiyani to'lash (kartadan yechish)
5	DeleteCard	Kartani o'chirish (ixtiyoriy)

ℹ️ Eslatma: Obuna API orqali saqlangan karta tokeni (cardId) orqali istalgan vaqtda to'lov amalga oshirilishi mumkin.

Foydalanuvchi kartasini yaratish

Endpoint details

POST BASE_URL/merchant/userCard/createUserCard/

Header: Authorization: Bearer ACCESS_TOKEN

Request body

Fields	Type	Required	Description
user_id	string	Yes	Savdogar tizimidagi foydalanuvchi ID
card_number	string	Yes	9860000000000000
expire_date	string	Yes	YYMM
phone_number	string	No	+998*********

json

12345

{
  "user_id": "user_001",
  "card_number": "8600...",
  "expire_date": "2612"
}

Success response

json

12345678

{
  "result": {
    "card_id": "122421a-xxxx-yyyy",
    "phone": "99890***00"
  },
  "error": null
}

Error response

json

1234567

{
  "result": null,
  "error": {
    "code": "invalid_card_number",
    "message": "Invalid card number"
  }
}

Foydalanuvchi kartasini tasdiqlash

Endpoint details

POST BASE_URL/merchant/userCard/confirmUserCardCreate/

Header: Authorization: Bearer ACCESS_TOKEN

Request body

Fields	Type	Required	Description
user_id	string	Yes	Foydalanuvchi ID
card_id	string	Yes	createUserCard javobidagi card_id
otp	string	Yes	SMS tasdiqlash kodi
card_name	string	No	Kartaga nom berish
pinfl	string	No	PINFL identifikator

json

1234567

{
  "user_id": "user_001",
  "card_id": "122421a...",
  "otp": "123456",
  "card_name": "Mening Kartam",
  "pinfl": "07803684736125"
}

Success response

json

1234567891011

{
  "result": {
    "user_id": "user_001",
    "card_id": "78a353ww-c4ff-42ee-...",
    "number": "860000******9999",
    "balance": 982807.31,
    "vendor": "Uzcard"
  },
  "error": null
}

Error response

json

1234567

{
  "result": null,
  "error": {
    "code": "invalid_otp",
    "message": "Invalid SMS code"
  }
}

Foydalanuvchi kartasini o'chirish

Endpoint details

POST BASE_URL/merchant/userCard/removeUserCard/

Header: Authorization: Bearer ACCESS_TOKEN

Request body

Fields	Type	Required	Description
userId	string	Yes	Foydalanuvchi ID
cardId	string	Yes	O'chiriladigan karta tokeni

Success response

json

1234

{
  "result": true,
  "error": null
}

Error response

json

1234567

{
  "result": null,
  "error": {
    "code": "card_not_found",
    "message": "Card not found"
  }
}

Foydalanuvchining barcha kartalarini olish

Endpoint details

POST BASE_URL/merchant/userCard/getAllUserCards/

Header: Authorization: Bearer ACCESS_TOKEN

Request body

Fields	Type	Required	Description
user_id	string	Yes	Foydalanuvchi ID

Success response

json

12345678910

{
  "result": [
    {
      "card_id": "78a353ww-c4ff-...",
      "number": "860000******9999",
      "vendor": "Uzcard"
    }
  ],
  "error": null
}

Pan Pinfl mosligini tekshirish

Karta tokeni (card_id) va foydalanuvchi PINFL raqami bir-biriga mosligini tekshirish.

Endpoint details

POST BASE_URL/merchant/card/check-pan-pinfl/

Header: Authorization: Bearer ACCESS_TOKEN

Request body

Fields	Type	Required	Description
card_id	string	Yes	Karta tokeni (ro'yxatdan o'tgan bo'lishi shart)
pinfl	string	Yes	14 xonali PINFL raqami

json

124

{
  "card_id": "78a353ww-c4ff-...",
  "pinfl": "52305035650013"
}

Success response

json

123456

{
  "result": {
    "match": true
  },
  "error": null
}

Avtorizatsiya

Barcha API so'rovlari uchun ikkita autentifikatsiya headerini yuborish kerak.

Endpoint details

Header:

http

12

Authorization: Bearer YOUR_API_KEY
Merchant-ID: 123

Parametrlar

Fields	Type	Description
Authorization	Header	`Bearer API_KEY` formatida token
Merchant-ID	Header	Savdogar identifikatori

To'lov

Kvitansiya yaratish va kartadan to'lov yechish.

Kvitansiya yaratish

POST BASE_URL/merchant/receipts/create/

Header: Authorization: Bearer ACCESS_TOKEN

Fields	Type	Required	Description
amount	integer	Yes	Summa (so'mda (UZS))
account	object	Yes	Buyurtma ma'lumotlari (order_id)

json

12345

{
  "amount": 500,
  "account": {
    "order_id": "1001"
  }
}

Kvitansiyani to'lash

POST BASE_URL/merchant/receipts/pay/

Header: Authorization: Bearer ACCESS_TOKEN

Fields	Type	Required	Description
transaction_id	string	Yes	Kvitansiya ID
card_id	string	Yes	Tasdiqlangan karta tokeni
user_id	string	Yes	Karta egasi ID

Success response

json

123456

{
  "result": {
    "status": 1
  },
  "error": null
}

Error response

json

1234567

{
  "result": null,
  "error": {
    "code": "insufficient_funds",
    "message": "Insufficient funds"
  }
}

Karta monitoring

Foydalanuvchi kartasining hozirgi holatini va balansi, muddatini tekshirish.

Endpoint details

POST BASE_URL/merchant/userCard/getSingleUserCard/

Header: Authorization: Bearer ACCESS_TOKEN

Request body

Fields	Type	Required	Description
user_id	string	Yes	Foydalanuvchi ID
card_id	string	Yes	Karta token ID

Success response

json

123456789

{
  "result": {
    "card_id": "78a353ww-c4ff-...",
    "number": "860000******9999",
    "balance": 982807.31,
    "vendor": "Uzcard"
  },
  "error": null
}

Error response

json

1234567

{
  "result": null,
  "error": {
    "code": "card_not_found",
    "message": "Card not found"
  }
}

P2P o'tkazmasi

Bir kartadan boshqa kartaga to'g'ridan-to'g'ri pul o'tkazish (Peer-to-Peer).

Endpoint details

POST BASE_URL/merchant/p2p/create/

Header: Authorization: Bearer ACCESS_TOKEN

Request body

Fields	Type	Required	Description
user_id	string	Yes	Yuboruvchi foydalanuvchi ID
card_id	string	Yes	Yuboruvchi karta tokeni
receiver_card	string	Yes	Qabul qiluvchi karta raqami
amount	integer	Yes	Summa (so'mda (UZS))

json

123456

{
  "user_id": "u123",
  "card_id": "78a353ww-c4ff-...",
  "receiver_card": "8600140000000000",
  "amount": 5000
}

Success response

json

1234567

{
  "result": {
    "transaction_id": "p2p_90001",
    : 1
  },
  "error": null
}

Error response

json

1234567

{
  "result": null,
  "error": {
    "code": "insufficient_funds",
    "message": "Insufficient funds"
  }
}

To'lovni ushlab turish (Hold)

Kartada ma'lum summani hold qilish (bloklash). Keyinchalik uni yechib olish (Charge) yoki bekor qilish (Dismiss) mumkin.

1. Hold yaratish

POST BASE_URL/merchant/hold/create/

Fields	Type	Required	Description
user_id	string	Yes	Foydalanuvchi ID
card_id	string	Yes	Karta tokeni
amount	integer	Yes	Hold summasi (SUMda)
time	integer	No	Hold vaqti (daqiqada). Max: 40320 (28 kun)
external_id	string	No	Tashqi identifikator

json

{
  "user_id": "u123",
  "card_id": "78a353ww-...",
  "amount": 100
}

json

{
  "result": { "transaction_id": "h_5001" },
  "error": null
}

2. Holdni yechib olish (Charge)

POST BASE_URL/merchant/hold/confirm/

Fields	Type	Required	Description
transaction_id	string	Yes	Hold tranzaksiya ID
amount	integer	Yes	Yechib olinadigan summa

json

{
  "transaction_id": "h_5001",
  "amount": 100
}

3. Holdni bekor qilish (Dismiss)

POST BASE_URL/merchant/hold/cancel/

Fields	Type	Required	Description
transaction_id	string	Yes	Bekor qilinadigan hold ID

json

{
  "transaction_id": "h_5001"
}

4. Hold holati (Status)

POST BASE_URL/merchant/hold/status/

Fields	Type	Required	Description
transaction_id	string	No*	Tranzaksiya ID
external_id	string	No*	*Kamida bittasi bo'lishi shart

Success response (Status)

json

123456789

{
  "result": {
    "transaction_id": "d1be13da-...",
    "status": "cancelled",
    "cancel_time": "2025-02-03 11:13:42",
    "amount": 1000,
    "payed_at": null
  },
  "error": null
}

Xato kodlari (Hold uchun)

Kod	Tavsif
hold_not_found	Hold topilmadi
hold_time_expired	Hold vaqti tugagan
invalid_amount	Summa noto'g'ri
transaction_not_found	Tranzaksiya topilmadi

HisobKartasi (Account2Card)

Savdogar hisobidan foydalanuvchi kartasiga pul o'tkazish.

Endpoint details

POST BASE_URL/merchant/account2card/

Header: Authorization: Bearer ACCESS_TOKEN

Request body

Fields	Type	Required	Description
card_number	string	Yes	Qabul qiluvchi karta raqami
amount	integer	Yes	Summa (so'mda (UZS))
description	string	No	Izoh

json

12345

{
  "card_number": "8600140000000000",
  "amount": 10000,
  "description": "Oylik to'lov"
}

Success response

json

1234567

{
  "result": {
    "transaction_id": ,
    "status": 1
  },
  "error": null
}

Error response

json

1234567

{
  "result": null,
  "error": {
    "code": "insufficient_merchant_balance",
    "message": "Insufficient merchant balance"
  }
}

⚠️ Diqqat: Account2Card operatsiyasi savdogar balansidan yechiladi. Yetarli balans bo'lishi shart.

Xizmat uchun to'lash

Ma'lum bir xizmat yoki provayderga to'lov amalga oshirish.

Endpoint details

POST BASE_URL/merchant/service/pay/

Header: Authorization: Bearer ACCESS_TOKEN

Request body

Fields	Type	Required	Description
user_id	string	Yes	Foydalanuvchi ID
card_id	string	Yes	Karta tokeni
service_id	string	Yes	Xizmat provayder ID
account	string	Yes	Abonent identifikatori
amount	integer	Yes	Summa (so'mda (UZS))

json

1234567

{
  "user_id": "u123",
  "card_id": "78a353ww-c4ff-...",
  "service_id": "beeline_uz",
  "account": "998901234567",
  "amount": 1000
}

Success response

json

1234567

{
  "result": {
    "transaction_id": "svc_70001",
    "status": 1
  },
  "error": null
}

Error response

json

1234567

{
  "result": null,
  "error": {
    "code": "service_unavailable",
    "message": "Service temporarily unavailable"
  }
}

To'lovni bo'lib to'lash (Split)

Yagona to'lovni bir nechta qabul qiluvchilarga bo'lib yuborish.

Endpoint details

POST BASE_URL/merchant/split/create/

Header: Authorization: Bearer ACCESS_TOKEN

Request body

Fields	Type	Required	Description
user_id	string	Yes	To'lovchi foydalanuvchi ID
card_id	string	Yes	Karta tokeni
total_amount	integer	Yes	Umumiy summa (so'mda (UZS))
splits	array	Yes	Qabul qiluvchilar ro'yxati

json

12345678910111213141516

{
  "user_id": "u123",
  "card_id": "78a353ww-c4ff-...",
  "total_amount": 10000,
  "splits": [
    {
      "merchant_id": "merchant_A",
      "amount": 7000
    },
    {
      "merchant_id": "merchant_B",
      "amount": 3000
    }
  ]
}

Success response

json

1234567

{
  "result": {
    "transaction_id": "split_80001",
    "status": 1
  },
  "error": null
}

Error response

json

1234567

{
  "result": null,
  "error": {
    "code": "total_amount_mismatch",
    "message": "Total amount does not match split sum"
  }
}

ℹ️ Eslatma: splits massividagi summalar yig'indisi totalAmount ga teng bo'lishi kerak.