Kirish

Ishlash printsipi (Stripe Checkout / Payme kabi "hosted checkout" modeli):

1. Siz API kalitingiz bilan buyurtma yaratasiz (summasi, tavsifi bilan).
2. Subo sizga checkoutUrl qaytaradi.
3. Siz mijozni shu havolaga yo'naltirasiz (redirect yoki yangi oyna).
4. Mijoz Subo sahifasida karta raqamini kiritadi va SMS kod bilan tasdiqlaydi.
5. Subo Atmos orqali pulni yechib oladi va sizga callbackUrl orqali xabar beradi.

Autentifikatsiya

API kalitingizni Subo admin panelida — Sotuv → Tashqi API bo'limida yaratasiz. Kalit faqat yaratilgan paytda bir marta to'liq ko'rsatiladi, shuning uchun darhol xavfsiz joyga saqlab qo'ying.

Har bir so'rovga Authorization headerini qo'shing:

Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Ishlash oqimi (diagramma)

Sizning serveringiz                Subo                          Mijoz brauzeri
       |                              |                                |
       |--- POST /orders (API key) -->|                                |
       |<---- { checkoutUrl } --------|                                |
       |                              |                                |
       |---- redirect mijozni checkoutUrl'ga -------------------------->|
       |                              |<---- karta + SMS kod ----------|
       |                              |---- Atmos orqali yechadi ----->|
       |<--- POST callbackUrl (webhook) ------------------------------->|
       |                              |                                |
       |--- GET /orders/:id (holatni tasdiqlash) ------>|              |

Buyurtma yaratish

So'rov maydonlari

So'rov namunasi

curl -X POST https://subo.uz/api/external/v1/orders \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amountTiyin": 5000000,
    "description": "Frontend kursi — 1-oy",
    "externalReference": "order-1234",
    "customerId": "user-777",
    "customerName": "Alisher Vali",
    "callbackUrl": "https://sizning-saytingiz.uz/webhooks/subo",
    "returnUrl": "https://sizning-saytingiz.uz/thank-you?order=1234"
  }'

Javob (201)

{
  "orderId": "b1e2c3d4-...",
  "status": "PENDING",
  "checkoutUrl": "https://subo.uz/pay/9f8e7d6c5b4a...",
  "externalReference": "order-1234",
  "customerId": "user-777",
  "amountTiyin": "5000000",
  "description": "Frontend kursi — 1-oy",
  "customerName": "Alisher Vali",
  "atmosTransactionId": null,
  "failureReason": null,
  "paidAt": null,
  "createdAt": "2026-09-11T12:00:00.000Z",
  "expiresAt": "2026-09-11T12:30:00.000Z"
}

Mijozni checkoutUrlga yo'naltiring (redirect yoki yangi tab). Havola 30 daqiqa amal qiladi.

Buyurtma holatini olish

Javob yuqoridagi bilan bir xil shaklda, joriy status bilan (PENDING / PAID / FAILED / EXPIRED). Webhook kelgach, holatni shu endpoint orqali qayta tekshirish tavsiya etiladi.

curl https://subo.uz/api/external/v1/orders/b1e2c3d4-... \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Checkout sahifasi

checkoutUrl — Subo domenida joylashgan, mustaqil to'lov sahifasi (https://subo.uz/pay/<token>). Uni brauzerda yangi oynada oching yoki to'g'ridan-to'g'ri shu manzilga redirect qiling. Sahifa login talab qilmaydi.

Sahifada mijoz: summani va tavsifni ko'radi → karta raqami + amal qilish muddatini kiritadi → telefoniga kelgan SMS kodni kiritadi → to'lov yakunlanadi.

Saqlangan karta (takroriy mijoz)

Agar buyurtma yaratishda customerId yuborsangiz va mijoz to'lovni muvaffaqiyatli yakunlasa, uning kartasi (Atmos token sifatida, shifrlangan holda) shu customerIdga bog'lab saqlanadi.

Keyingi safar bir xil customerId bilan yangi buyurtma yaratsangiz, checkout sahifasi kartani qayta kiritishni so'ramaydi — mijozga saqlangan karta (masalan •••• 1234) ko'rsatiladi va u faqat bitta tugma bosib to'laydi (SMS kod ham so'ralmaydi, chunki karta avval tasdiqlangan).

Mijoz "Boshqa karta bilan to'lash"ni tanlasa, oddiy karta kiritish shakli ochiladi va yangi karta saqlangan kartani almashtiradi.

Webhook

Buyurtma yakunlangach (muvaffaqiyatli yoki muvaffaqiyatsiz), agar callbackUrl berilgan bo'lsa, o'sha manzilga POST so'rovi yuboriladi:

{
  "event": "order.paid",
  "orderId": "b1e2c3d4-...",
  "externalReference": "order-1234",
  "amountTiyin": "5000000",
  "status": "PAID",
  "paidAt": "2026-09-11T12:05:32.000Z"
}

event qiymati order.paid yoki order.failed bo'ladi.

Xatoliklar

{
  "statusCode": 400,
  "message": "Karta balansida mablag' yetarli emas",
  "error": "Bad Request"
}

Sandbox test kartalari

Agar admin hisobingiz Atmos sandbox rejimida bo'lsa, quyidagi test kartalaridan foydalaning (SMS kodi hammasi uchun 111111):

Cheklovlar

• Checkout havolasi yaratilgandan keyin 30 daqiqa amal qiladi.
• Summa: minimal 1 000 tiyin (10 so'm), maksimal 500 000 000 tiyin (5 000 000 so'm).
• Har bir admin hisobida bitta faol API kaliti bo'ladi — yangisini yaratsangiz, eskisi avtomatik bekor bo'ladi.