Tashqi to'lov API

Kirish

Bu — Stripe Checkout / Payme kabi "hosted checkout" modeli: karta ma'lumotlarini siz emas, Subo qabul qiladi va saqlaydi (Atmos tanlanganda), yoki mijoz Click/Payme'ning o'z sahifasida to'laydi (o'sha provayderlar tanlanganda). Ikkala holatda ham sizning integratsiya kodingiz bir xil qoladi.

Autentifikatsiya

POST /api/external/v1/orders HTTP/1.1
Host: subo.uz
Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Ishlash oqimi

1. Serveringiz POST /orders so'rovini API kaliti bilan yuboradi.
2. Subo buyurtmani yaratadi va javobda checkoutUrl qaytaradi.
3. Mijozni shu checkoutUrlga yo'naltirasiz.
4. Mijoz to'lovni amalga oshiradi — Subo checkout sahifasida (Atmos) yoki Click/Payme sahifasida.
5. Subo to'lov natijasini callbackUrlingizga webhook orqali yuboradi.
6. Serveringiz GET /orders/:orderId bilan holatni yakuniy tasdiqlaydi.

Click yoki Payme tanlanganda 3- va 4-qadamlar orasida qo'shimcha bir bosqich bor: mijoz Click/Payme'ning o'z sahifasida to'laydi, ular esa to'g'ridan-to'g'ri Subo bilan (sizdan mustaqil ravishda) gaplashib, natijani tasdiqlaydi. Bu qism butunlay Subo tomonidan boshqariladi — sizga hech qanday qo'shimcha kod yozish shart emas.

To'lov provayderlari

Subo 3 ta to'lov tizimini qo'llab-quvvatlaydi: Atmos, Click va Payme. Har birini admin panelda — Sotuv → Tashqi API → To'lov provayderlari bo'limida alohida sozlaysiz. Bir nechta provayder bir vaqtda faol bo'lishi mumkin.

Buyurtma yaratishda provider maydoni orqali qaysi tizim ishlatilishini tanlaysiz. Ko'rsatilmasa, sozlangan birinchi provayder avtomatik ishlatiladi. Sizning integratsiyangiz kodi provayderdan qat'i nazar o'zgarmaydi.

Buyurtma yaratish

POST /api/external/v1/orders HTTP/1.1
Host: subo.uz
Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

// so'rov tanasi
{
  "amountTiyin": 5000000,
  "provider": "CLICK",
  "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",
  "provider": "CLICK",
  "checkoutUrl": "https://subo.uz/pay/9f8e7d6c5b4a...",
  "externalReference": "order-1234",
  "customerId": "user-777",
  "amountTiyin": "5000000",
  "description": "Frontend kursi — 1-oy",
  "customerName": "Alisher Vali",
  "atmosTransactionId": null,
  "providerTransactionId": null,
  "failureReason": null,
  "paidAt": null,
  "createdAt": "2026-09-12T12:00:00.000Z",
  "expiresAt": "2026-09-12T12:30:00.000Z"
}

curl -X POST https://subo.uz/api/external/v1/orders \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amountTiyin": 5000000,
    "provider": "CLICK",
    "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"
  }'

const res = await fetch('https://subo.uz/api/external/v1/orders', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amountTiyin: 5000000,
    provider: 'CLICK',
    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',
  }),
});
const order = await res.json();
// mijozni order.checkoutUrl'ga yo'naltiring

Buyurtma holatini olish

GET /api/external/v1/orders/b1e2c3d4-... HTTP/1.1
Host: subo.uz
Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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.

Atmos tanlangan bo'lsa: mijoz summani va tavsifni ko'radi → karta raqami + amal qilish muddatini kiritadi → SMS kodni kiritadi → to'lov yakunlanadi.

Click yoki Payme tanlangan bo'lsa: sahifa mijozni darhol o'sha provayderning o'z to'lov sahifasiga yo'naltiradi.

Saqlangan karta (takroriy mijoz)

Faqat Atmos provayderi uchun. 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 ko'rsatiladi va u faqat bitta tugma bosib to'laydi.

Webhook

POST https://sizning-saytingiz.uz/webhooks/subo HTTP/1.1
Content-Type: application/json

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

app.post('/webhooks/subo', async (req, res) => {
  const { orderId } = req.body;

  // Ishonchli manbadan tasdiqlang — tanaga to'g'ridan-to'g'ri ishonmang.
  const order = await fetch(
    `https://subo.uz/api/external/v1/orders/${orderId}`,
    { headers: { Authorization: 'Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' } }
  ).then((r) => r.json());

  if (order.status === 'PAID') {
    // ... obunani faollashtiring / buyurtmani yakunlang ...
  }

  res.sendStatus(200); // muhim: aks holda qayta urinib turadi
});

Xatoliklar

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

Sandbox muhiti

POST https://sizning-saytingiz.uz/webhooks/subo HTTP/1.1
Content-Type: application/json

{
  "event": "order.paid",
  "orderId": "b1e2c3d4-...",
  "externalReference": "order-1234",
  "amountTiyin": "4900000",
  "status": "PAID",
  "paidAt": "2026-09-25T13:40:11.000Z",
  "sandbox": true
}

Atmos test kartalari

Atmos test rejimida quyidagi test kartalaridan foydalaning (SMS kodi hammasi uchun 111111):

Click va Payme uchun test kartalar o'sha tizimlarning o'z hujjatlarida beriladi.

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 bir vaqtning o'zida 3 tagacha faol API kaliti bo'lishi mumkin (masalan alohida Sandbox va Production kalitlari).

Savol-javob